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INTRODUCTION 


Welcome to the Microsofte QuickCm Compiler! You have purchased one of 
the most powerful packages available for working with the C language, an 
ideal set of tools for beginning programmers and experienced software 
developers alike. 


The Microsoft QuickC Compiler is a full implementation of the C pro- 
gramming language that combines the power, portability, and flexibility of 
C with a complete development environment. It includes the following 
features: 


=m Get All the Tools You Need 


in an Integrated Programming Environment 


The Microsoft QuickC Compiler provides the program-development tools 
you need in a single package: an integrated program editor, compiler, and 
debugger (Chapter 8). Using the Microsoft QuickC Compiler, you can com- 
pile, run, debug, edit, and recompile programs without ever leaving the 
programming environment. The QuickC compiler can create programs for 
in-memory execution, or it can create stand-alone object files for use in 
libraries plus executable files for later execution under DOS. 


Since most standard C library functions are built into the programming 
environment, it is not usually necessary to link with an external library. 
Any standard C library routines that are not built into the environment 
can be loaded in a user-configurable library known as a Quick library. 


m Learn Quickly with a WordStar-Compatible Editor 

Learning the QuickC editor is a simple matter. If you are familiar with the 
MicroPro WordStare program, you already know most of the QuickC edit- 
ing commands, since they they are exactly the same as the corresponding 
WordStar commands. (Section 7.1.1 describes the QuickC editing keys.) 

m= Find Bugs Fast with an Integrated Debugger 

QuickC includes many of the capabilities of professional debuggers, which 


make it easy to track down errors in program logic. Using the QuickC 
debugger, you can 
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e Step through program execution line by line 
e Set multiple breakpoints 


e Display the values of variables in a separate window during pro- 
gram execution 


e Switch between the program and program-output displays 


e Search for particular functions in the source program 


Sections 8.2-8.2.4 show how to use these debugging facilities. If even this 
list of features isn’t enough, you can debug QuickC programs by using the 
Microsofte CodeViewe window-oriented debugger provided with the 
Microsoft C Optimizing Compiler and other Microsoft language products. 


= Get Help At Your Fingertips 


Do you have a question about the syntax of a C statement? About the 
types of arguments to a library routine? About the QuickC editor keys? 
Get answers fast using QuickC’s context-sensitive, on-line help facility. 
Browse through a menu of topics, or simply highlight a function name and 
press a key. You don’t even need to leave the editor; information appears 
in a separate window at the top of the screen. 


m Add Visual Impact to Programs with the Graphics Library 


The graphics library provided with the QuickC library gives you the power 
you need to write sophisticated graphics applications. This library sup- 
ports the full range of IBM and IBM-compatible display adapters, includ- 
ing the IBM Video Graphics Array (VGA), Monochrome Display Adapter 
MDA), Color/Graphics Adapter (CGA), and Enhanced Graphics Adapter 
EGA). See Chapter 4 for information about the graphics library. 


m Write Programs Fast, Then Optimize 
with the Microsoft C Optimizing Compiler 


Since the Microsoft QuickC Compiler is fully compatible with Version 5.0 
of the Microsoft C Optimizing Compiler at the source-file and object-file 
levels, you are assured of a smooth upgrade path when you need the added 
flexibility and power that the Microsoft C Optimizing Compiler provides. 
If you are developing programs with the Microsoft C Optimizing Compiler, 
you can use the Microsoft QuickC Compiler to speed up the early phases 
of program development, then use the Microsoft C Optimizing Compiler to 
fine-tune program performance. 
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= Start Fast with the OS/2-Compatible User Interface 


The user interface for the Microsoft QuickC Compiler is easy to learn. 
Simply select commands from menus using the keyboard, an optional 
mouse, or both, or press special keys to carry out commands without open- 
ing a menu. The QuickC user interface looks and works very much like 

the new Microsoft presentation-manager interface to the OS/2 operating 
system. 


= Maintain Large Programs Automatically 


Maintaining large programs with large numbers of modules is automatic 
with the Microsoft QuickC Compiler. As you edit the modules that make 
up a program, you add them to a “program list.” When you rebuild the 
program, QuickC saves you time by recompiling only the modules that 
have been changed since the last program build. 


The program list is saved in a file that is compatible with the MAKE 
program-maintenance utility; consequently, programs can be updated 
automatically outside the QuickC programming environment. 


m Get the Results You Want with These Additional Features 
Microsoft QuickC offers the following additional features: 


e Acomplete tool kit of utility programs to meet almost every pro- 
gramming need. This tool kit includes the QCL compiler/linker 
driver; the Microsoft Overlay Linker, LINK; the Microsoft Library 
Na th LIB; and the Microsoft Program-Maintenance Utility, 


e Simplified memory management using any of four memory models. 
The QCL compiler/linker driver supports the small, medium, com- 
pact, and large memory models. 


e Outstanding reference documentation. The documentation includes 
complete reference documentation for the C programming language 
and standard C library routines, including hundreds of complete 
program examples. 
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System Requirements 


The Microsoft QuickC Compiler requires the following minimum 
configuration: 


e An IBMe Personal Computer or strict “compatible” running MS- 
DOSe or PC-DOSe Version 2.1 or later 


e Two floppy-disk drives or one floppy-disk drive and a hard disk 
e 448K RAM available memory 


Using This Manual 


The Microsoft QuickC Compiler is designed for a wide range of users, from 
beginners who are new to programming to experienced developers who are 
fluent in the C language. Different parts of the manual are intended for 
users with different needs. 


The following paragraphs explain how this manual is organized, suggest 
different paths for different types of users, and describe the other manuals 
provided in the package. 


How this Manual is Organized 


Part 1 of this manual, “Getting Started,” explains how to install the 
Microsoft QuickC Compiler, introduces you to the QuickC programming 
environment, and describes important features of the C language for users 
familiar with other languages such as BASIC and Pascal. This part also 
shows you how to use the graphics library Provide? with the Microsoft 
QuickC Compiler. 


Part 2, “The QuickC Programming Environment,” explains how to edit, 
compile, and debug programs within the QuickC programming environ- 
ment. 


Part 3 of this manual, “The QuickC Tool Kit,” explains how to compile 
and link programs by using the QCL and LINK programs; how to build 
Quick libraries by using LINK and build stand-alone libraries by using 
the LIB utility; and how to maintain programs by using the MAKE util- 
ity. 
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The appendixes to this manual contain additional information you may 
find helpful, such as: 


e A table of ASCII character codes 
e A description of QuickC memory models 


e A description of interfaces between Microsoft C and the Microsoft 
Macro Assembler (MASM) 


e A list of error messages 


A handy quick reference card included in this manual lists QuickC editing 
and debugging keys and key sequences. 


What to Read in this Manual 

All users should read Chapter 1, “Installing and Starting QuickC,” to get 

instructions for installing the compiler software. If you want introductory 
hands-on practice with the compiler, you will want to go through the brief 
sample session described in Section 1.7.4. 


Where to go next depends on your particular needs, as described below: 


= Users New to Programming and the C Language 

If you are learning programming and C at the same time, refer to the list 
of tutorial texts under “Resources for Learning” in this introduction. 

. Programmers Who are New to the C Language 

If you have some programming background but have never programmed in 
C before, refer to Chapter 3, “C Quick Start,” for information about par- 
ticular features of C and the differences between C and other languages 
such as BASIC and Pascal. 

m =Users Who Want to Program with QuickC Graphics 

Read Chapter 4, “Graphics Quick Start,” for instructions on writing pro- 


grams with the graphics functions provided with the Microsoft QuickC 
Compiler. 
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m Users Who are New 
to Integrated Programming Environments 


Read Chapter 2, “Introducing the QuickC Programming Environment,” 
for an introduction to the components of the QuickC programming 
environment. Then read Part 2, “The QuickC Programming Environ- 
ment,” to learn how to use the editor, compiler, and debugger built into 
the QuickC environment. 


m™ Users Who Are Interested 
in Other Tools Provided with QuickC 


Read Part 3, “The QuickC Tool Kit,” for descriptions of the QCL 
compiler/linker driver, the LINK linker, the LIB library manager, and 
the E program-maintenance utility. 


Other Manuals You Get with QuickC 


Two additional manuals are provided in the Microsoft QuickC Compiler 
package: 


e The Microsoft C Language Reference decribes Microsoft’s ANSI- 
compatible implementation of the C language. 


e The Microsoft C Run-Time Library Reference describes the more 
than 350 library routines and 34 include files provided with the 
Microsoft QuickC Compiler. 


Notational Conventions 


This manual uses the following notation: 


Example 

of Convention Description of Convention 

Example The typeface shown in the left column is used 
to simulate the appearance of information 
that would be printed on the screen or by the 
printer. 

placeholders Words in italics are placeholders in command- 


line and option specifications for types of 
information that you must supply. Italics are 
also occasionally used in the text for 
emphasis. 
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DOS NAMES, 
FILE NAMES, and 
MACROS 


Reserved words 


[optional items] 


{ choice1|choice2} 


“Defined term” 


Repeating 
elements... 


KEY NAMES 
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Bold capital letters are used for the names of 
executable files and files provided with the 
product, for environment variables, for mani- 
fest constants, for macros, and for registers. 
These commands include built-in DOS com- 
mands such as SET, as well as the names of 
programs provided with the QuickC package. 


Bold type indicates text that must be typed 
as shown. Text that is normally shown in bold 
type includes operators, keywords, library 
functions, commands, options, and preproces- 
sor directives. Examples include the C key- 
word int and the function name fopen. 


Double brackets enclose optional fields in 
command-line and option specifications. 


Braces and a vertical bar indicate that you 
have a choice between two or more items. 
Braces enclose the choices, and vertical bars 
separate the choices. 


Quotation marks set off terms defined in the 
text. For example, the term “far” appears in 
quotation marks the first time it is defined. 
Quotation marks also set off command-line 
prompts in text. 


Some C constructs require quotation marks. 
Quotation marks required by the language 
have the form " " rather than “”. 


Three dots (also known as “ellipsis eee ae 
lowing an item indicate that more items hav- 
ing the same form may be entered. 


A column of dots in syntax lines and program 
examples shows that a portion of the program 
has been omitted. 


Small capital letters are used for the names of 
keys you must press. Key sequences are indi- 
cated by small capitals separated by a plus 
sign (+). Examples include ENTER and 
CTRL+C. 
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The names of the keys in this manual corres- 
pond to the names printed on IBM Personal 
Computer key tops. If you are using a 
different machine, these keys may have 
slightly different names. 


The group of cursor-movement (sometimes 
called “arrow” ) keys located on the numeric 
keypad to the right of the main keypad are 
called the DIRECTION keys. Each individual 
DIRECTION key is referred to either by the 
direction of the arrow on the key top (LEFT, 
RIGHT, UP, DOWN), or by the name on the key 
top (PGUP, PGDN). 


The carriage-return key is referred to as 
ENTER. 


Resources for Learning 


You may want to explore C further with one or more of the books listed 
below. They are listed in ascending order of difficulty, from beginning to 
advanced. 


Hancock, Les, and Morris Krieger. The C' Primer, 2d ed. New York: 
McGraw-Hill, 1985. (A beginner’s guide to programming in the C 
language.) 


Schildt, Herbert. C Made Easy. Berkeley, CA: Osborne/McGraw-Hill, 
1985. (A good introduction to C for the reader who already knows 


BASIC.) 


Waite, Mitchell, Stephine Prata, and Donald Martin. C Primer Plus. 
Indianapolis, IN: Howard W. Sams, Inc., 1984. (The best-selling intro- 
duction to the C language.) 


Plum, Thomas. Learning to Program in C. Cardiff, New Jersey: Plum 
Hall, Inc., 1983. (A widely used introductory college text on computer 
programming using the C language.) 


Kochan, Stephen. Programming in C. Hasbrouck Heights, NJ: Hayden 
Book Company, Inc., 1983. (A comprehensive introduction to C with 
some emphasis on the UNIXe environment.) 


Harbison, Samuel P. and Guy L. Steele, Jr. C: A Reference Manual, 2d 
ed. Englewood Cliffs, NJ: Prentice-Hall, Inc., 1987. (An outstanding 
reference to the C language. The second edition incorporates the ANSI 
standard.) 
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Kernighan, Brian W., and Dennis M. Ritchie. The C Programming 
Language. Englewood Cliffs, NJ: Prentice-Hall, Inc., 1978. (The origi- 
nal, classic C book. Known to insiders as “IX & R” or as “the white 
book.” Useful after you have learned C.) 


Tondo, Clovis L., and Scott E. Gimple. The C Answer Book. Engle- 
wood Cliffs, NJ: Prentice-Hall, Inc., 1985. (A collection of answers to 
the exercises in K & R. A companion volume to K & R.) 


Jaeschke, Rex. Solutions in C. Reading, Massachusetts: Addison- 
Wesley, 1986. (A useful collection of C programming tips.) 


Ward, Robert. Debugging C. Indianapolis, Indiana: Que Corporation, 
1986. (A guide to the techniques of debugging C programs.) 


Schustack, Steve. Variations in C. Redmond, Washington: Microsoft 
Press, 1985. (A guide to programming business applications in C.)* 


Hansen, Augie. Proficient C. Redmond, Washington: Microsoft Press, 
1987. (A guide to advanced C programming in the MS-DOS environ- 
ment. 


Getting Help from Microsoft 


If you feel you have discovered a problem in the software, please report the 
problem using the Product Assistance Request at the back of this manual. 


If you have comments or suggestions regarding any of the manuals accom- 
panying this product, please use the Documentation Feedback Card, also 
at the back of this manual. 


* 
Microsoft Press books are available wherever books and software are sold. To order by 
phone, call 1-800-638-3030; in Maryland, call collect 824-7300. For a complete catalog of 
Microsoft Press books, write to: Microsoft Press, 16011 NE 36th Way, Box 97017, Redmond, 
WA 98073-9717. 
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STARTED 


Germ Sum | 


This part of the manual will get you started pro- 
gramming with the Microsoft QuickC Compiler. 


Chapter 1 explains how to install the compiler 
by using the SE'TUP program and how to start 
and exit from the QuickC programming environ- 
ment; it also describes a sample session in which 
you can load, compile, and run a program by 
using the QuickC compiler. 

Chapter 2 describes the QuickC programming 
environment and common operations within it. 
This chapter is designed for users who want to 
experiment with QuickC before reading about 
menus and commands in detail. 

Chapter 3 introduces the C programming 
language to users who are familiar with other 
languages such as Pascal or BASIC. | 
Chapter 4 shows how to write graphics programs 
by using the graphics-library routines. 
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Installing and Starting QuickC 


This chapter tells you how to install and start the Microsoft QuickC Com- 
piler. Before you begin using the compiler, be sure to 


Back up your product disks (see Section 1.1). 
. Check the contents of your disks (see Section 1.2). 
3. Read the READMEDOC file on your working copy of the Pro- 


duct distribution disk to learn about changes and additions made 
to the software after this manual was printed. 


4. Run the SETUP program to install the software (see Sections 
1.3.1.1-1.3.1.2 and 1.3.2.1-1.3.2.2). 


5. Set up your DOS environment so that QuickC can find the files 
that it needs (see Section 1.4). 


Several DOS procedures are mentioned in this chapter. In particular, the 
DOS SET and PATH commands are used to give values to DOS environ- 
ment variables. If you are unfamiliar with any of the DOS procedures men- 
tioned, consult your DOS user’s guide for instructions. 


Note 


In this manual, the term “DOS” is used to refer to both MS-DOS and 
PC-DOS. 


1.1 Backing Up Your Disks 


After you have unwrapped the disks in your package, the first thing you 
should do is to make working copies, using the DOS COPY command or 
the DISKCOPY utility. Save the original disks for making future work- 
ing copies. 


1.2 Checking Disk Contents 


When you open your compiler package for the first time, you may want to 
verify that you have a complete set of software.. The Product distribution 
disk included in your compiler package contains a file that is named 
PACKING.LST;; this file lists and describes the files and manuals that 
make up the Microsoft QuickC package. 
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To accommodate new features that may be added to the Microsoft QuickC 
Compiler, certain files or programs can be moved to disks other than the 
disks described in this manual. If you cannot find a file or program that 
you need, see the PACKING.LST file to find out which distribution disk 
contains that file or program. 


1.3 Installing QuickC 


Use the SETUP program provided on your working copy of the Libraries 
#1 distribution disk to install your QuickC software. The sections that 
follow give information about 


Exactly what SETUP does when it installs compiler software 


2. How torun SETUP to install the compiler software on a hard- 
disk or floppy-disk system 


3. How to set up the DOS environment so that QuickC can find the 
files that it needs 


Note 


If you also have Version 5.0 of the Microsoft C Optimizing Compiler, 
skip the installation procedure described here and run the version of 
SETUP provided with the Microsoft C Optimizing Compiler. The 
Version 5.0 SETUP installs both the Microsoft C Optimizing Com- 
piler and the Microsoft QuickC Compiler. See Chapter 2 of the 
Microsoft C Optimizing Compiler User’s Guide for instructions. 


1.3.1 Installing on a Hard-Disk System 

Sections 1.3.1.1—1.3.1.6 give instructions for installing the Microsoft 
QuickC Compiler on a hard-disk system. 

1.3.1.1 What SETUP Does on a Hard-Disk System 


When you install QuickC on a hard-disk system, the SETUP program 
does the following: 
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e Copies all necessary files to the directories or disks you specify. 


e Builds a stand-alone library for each memory-model/math-package 
combination you specify on the SETUP command line. Many 
standard C library routines are built into the QuickC programming 
environment; however, in some cases, the QuickC compiler searches 
the libraries that SETUP builds to find routines that cannot be 
found otherwise. Also use these libraries if you create programs 
outside of the QuickC programming environment. 


e Creates a batch file named NEW-VARS.BAT that sets the 
values of DOS environment variables so that QuickC can find the 
files it needs. 


e Creates a file named NEW-CONF.SYS containing the appropri- 
ate settings for the files and buffers parameters in your 
CONFIG.SYS file. 


1.3.1.2 Running SETUP on a Hard-Disk System 


When you are ready to run SETUP, insert your working copy of the 
Libraries #1 distribution disk in drive A. Then enter a command line of 
the following form: 


SETUP H C:\ dest {S|M|C|L} ... {EM|87}... [GR] [\ din] [\ enel] [\ 2d] 


Warning 


Several of the arguments that you give SETUP are directory names. If 
the directory you specify does not exist, SETUP creates the directory 
automatically. 


SETUP overwrites the existing files as it installs new files with the 
same names. Do not give SETUP the name of an existing directory, 
unless you don’t mind overwriting the files in that directory or you 
know that no files in that directory have the same names as the com- 
piler files. 


Each item (or “argument”) on the SETUP command line shown above 
gives SETUP information about how you want to install the QuickC 
compiler. Optional arguments are shown in double brackets ([ ) If you 
leave out an optional argument, SETUP uses the appropriate default. 
Some optional arguments allow you to type a question mark (?) to choose 
the default. 


Argument 


S, M,C, L 


EM, 87 
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! These are the arguments you can type on the SETUP command line; for a 
! brief on-line explanation of these arguments, type SETUP with no argu- 
ments while the Program distribution disk is in drive A. 


Meaning 


Type H to tell SETUP that you are installing on 
a hard-disk system. 


Type C: to tell SETUP that you are installing on 
drive C, immediately followed by the name of the 
“destination” directory for the installation. 
SETUP considers all other names that you give 
on the command line to be subdirectories of this 
directory. 


Type one or more of these letters, separated by 
spaces, to tell SETUP which memory models you 
will use. Type M, since the medium memory model 
is the default for the QuickC programming envi- 
ronment. If you will be developing programs out- 
side of the QuickC programming environment 
(using the QCL command discussed in Chapter 9, 
‘Compiling and Linking Programs”), type S, since 


- the small memory model is the default for the 


QCL command. Also, if you will be using them, 
type C (compact memory model), or L (large 
memory model). 


SETUP uses the memory-model arguments and 
the floating-point-math arguments ne below) that 
you give to determine which libraries to build. 
Combined libraries speed up the process of creat- 


ing programs; however, because the combined 


libraries are large, you should specify only those 
memory models that you know you will use. (If you 
use more than one memory model, you may also 
want to use the uncombined libraries instead of 
taking up disk space for combined libraries; see 
Section 1.4 for more information.) 


Type either or both of these arguments to tell 
SETUP how you want to handle floating-point 
math operations in your programs. 


Ordinarily, type EM for this option to tell QuickC 
that you will be using a floating-point emulator 
rather than an 8087 or 80287 coprocessor. (See 
Section 9.3.5 if you need more information about 
handling floating-point math in programs.) 


 Seko p_agenses 
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’ if you develop programs that perform 
c, mathematical, or financial calculations 


\ we de il numbers and that will always run on sys- 


th coprocessors. Typing 87 builds an addi- 


ut creating programs with this library 
hem smaller and faster. 


brary, which requires substantial disk 
ac \\e 


Type GR if you want to build the QuickC graph- 
ics functions (described in Chapter 4 of this 
manual and in the Microsoft C Run-Time Library 
Reference) into the library that SETUP builds. 
This option makes the library approximately 50I¢€ 
larger. If you do not give this option, graphics 
functions are not included. The QuickC compiler 
must be able to find the library that is named 
GRAPHICS.LIB if your program uses QuickC 
graphics functions. See Section 1.5 for more infor- 
mation. 


Type the subdirectory of dest in which you want to 
install the compiler executable files, including the 
compiler, linker, and utilities. If you leave out this 
argument or type a question mark (?) for it, 
SETUP uses the \BIN subdirectory by default. 


Type the subdirectory of dest in which you want to 
install include files. If you leave out this argument 
or type a question mark (?) for it, SETUP uses 
the \INCLUDE subdirectory by default. 


Type the subdirectory of dest in which you want to 
install library files. If you leave out this argument 
or type a question mark (?) for it, SETUP uses 
the \LIB subdirectory by default. 


SETUP automatically creates the following subdirectories: 


e Asubdirectory named \TMP that the compiler uses for temporary 
files during compilation 


e Asubdirectory of the executable-file directory named \SAMPLE, 
in which SETUP installs demonstration programs 


m= Examples 


SETUP- HA CeXyM EM? 2 2 


The command line above tells SETUP to install the compiler software in 
the default subdirectories of the root directory (\) on hard-disk drive C. 
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The default subdirectories are \BIN for compiler and utility executable 
files, \INCLUDE for include files, and \LIB for library files. SETUP 
builds the appropriate library for the medium memory model and the emu- 
lator floating-point math package and names this library MLIBCE.LIB. 


SETUP H C:\QC S MC L EM GR 87 \BINDIR \INC \LIBS 


The command line above tells SETUP to install the compiler software in 
the given subdirectories of the \QC directory on hard-disk drive C. Exe- 
cutable files are installed in \QC\BINDIR; include files are installed in 
\QC\ INC; library files are installed in \QC\LIBS; and demonstration files 
are installed in \QC\BINDIR\SAMPLE. Library files are built for all 
available memory models and floating-point math packages (eight libraries 
total). Each library includes the Microsoft C graphics functions. 


1.3.1.3 Building Libraries on a Hard-Disk System 


After you press ENTER, SETUP begins to build and install libraries. 
SETUP prompts you when to swap disks in drive A. 


SETUP reads each memory-model argument (S, M, C, or L) and floating- 
point-math argument (EM and 87) that you have given on the command 
line and builds one library for each possible combination of the two. 
SETUP displays the names of the libraries it is building as it builds them. 


SETUP also names the libraries it builds based on the memory model(s) 
and floating-point-math package(s) you choose. Each default library name | 
has the following form: 


{S|M|C{L}LIBC{E| 7}.LIB 


The first character of the library name is the same as the memory-model 
argument: S for the small (default) memory model, M for the medium 
memory model, C for the compact memory model, or L for the large mem- 
ory model. The last character of the base name (the part of the name 
before the .LIB extension) is determined by the floating-point-math argu- 
ment: E if the EM argument was given, or 7 if the 87 argument was 
given. 


For example, the library named MLIBCE.LIB supports the medium 
memory model and the emulator floating-point-math package, the defaults 
for the QuickC programming environment. The library named 
SLIBC7.LIB supports the small memory model and the 8087 /80287 
floating-point-math package, which can be used only for programs run on 
machines with a math coprocessor. 
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Note 


For ease of discussion, the remainder of this manual uses the default 
names to identify libraries that support particular combinations of 
memory models and math packages. 


1.3.1.4 Deleting Library Components 
SETUP displays the following additional prompt: 


Setup no longer needs the library sub-components and you do not 
normally need them to compile and link your C program. Do you want 
to delete them? [y/n] 


If you use combinations of memory models and floating-point-math pack- 
ages other than those you gave on the SETUP command line, you may 
want to keep the uncombined libraries. However, if you will only be using 
the models and math packages supported by your combined libraries, you 
can delete the uncombined libraries. Enter Y or y to delete the uncom- 
bined libraries, or enter N or nif you want to keep them. 


1.3.1.5 Completing Installation © 


SETUP performs several additional steps, including creating the 
NEW-VARS.BAT and NEW-CONF.SYS files. 


1.3.1.6 Setting Up the DOS Environment on a Hard-Disk System 


The final step of installation is to set up the DOS environment so that the 
QuickC compiler can find the files that it needs. 


SETUP automatically creates a batch file named NEW-VARS.BAT. 
Use NEW-VARS.BAT to set up your DOS environment variables so 
that the compiler and linker can find the files they need. 


If you wish, you can add the SET commands in the NEW-VARS.BAT 
file to yur AUTOEXEC.BAT file so that the DOS environment is set 


up correctly each time you boot your system. 


In addition to NEW-VARS.BAT, SETUP creates a file named 
NEW-CONF.SYS. This file sets the files and buffers parameters to 
appropriate values for the Microsoft QuickC Compiler. You can either 
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replace your existing CONFIG.SYS file with NEW-CONF.SYS or 
copy the buffers and files settings from NEW-CONF.SYS to your exist- 
ing CONFIG.SYS file. 


SETUP installs NEW-VARS.BAT and NEW-CONF.SYS in the sub- 
directory of dest where you installed the QuickC executable files (by de- 
fault, in dest\ BIN\SAMPLE). 


1.3.2 Installing on a Floppy-Disk System 


Sections 1.3.2.1-1.3.2.4 give instructions for installing the Microsoft 
QuickC Compiler on a floppy-disk system. Note that these instructions 
assume that you will be running SETUP from drive A; if you prefer to 
run SETUP from drive B, simply substitute “drive B” for “drive A” and 
“drive A” for “drive B” in the following instructions. 


1.3.2.1 What SETUP Does on a Floppy-Disk System 


When you install QuickC on a floppy-disk system, the SETUP program 
builds a stand-alone library for each memory-model/math-package combi- 
nation you specify on the SETUP command line. Many standard C 
library routines are built into the QuickC programming environment; 
however, in some cases, the QuickC compiler searches the libraries that 
SETUP builds to find routines that cannot be found otherwise. Also use 
these libraries if you create programs outside of the QuickC programming 
environment. 
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1.3.2.2 Running SETUP on a Floppy-Disk System 


Before you run SETUP on a floppy-disk system, determine how many 
blank, formatted floppy disks you will need to hold the libraries that 
SETUP builds. You need one blank, formatted disk for each memory 
model you will be using, plus one “scratch” disk; if you will be using only 
the default memory model for the QuickC programming environment 
(medium model), two disks are all you need. SETUP places each library 
that it builds on a separate floppy disk. 


After you format the required number of disks, insert your working copy 
of the Libraries #1 distribution disk in drive A. Then enter a command 
line of the following form: 


SETUP F B: {S|M|C|L}... {EM|87} [GR] 


Each item (or “argument”) on the SETUP command line gives SETUP 
information about how you want to install the QuickC compiler. Optional 
arguments are shown in double brackets (I ]). If you leave out an optional 
argument, SETUP uses the appropriate default. Some optional argu- 
ments allow you to type a question mark (?) to choose the default. 


These are the arguments you can type on the SETUP command line; for a 
brief on-line explanation of these arguments, type SETUP with no argu- 
ments while the Program distribution disk is in drive A. | 


Argument Meaning 


F Tells SETUP that you are installing on a floppy- 
disk system. 


B: Type B: to tell SETUP that you are creating 
libraries on the disks in drive B. 


S, M, C, L Tells SETUP which memory model(s) you will 
use. Type one or more letters, separated by spaces. 
Type M, since the medium memory model is the 
default for the QuickC programming environment. 
If you will be developing programs outside of the 
QuickC programming environment (using the 
QCL command discussed in Chapter 9, “Compil- 
ing and Linking Programs”), type S, since the 
small memory model is the default for the QCL 
command. Also, if you will be using them, type C 
boo nae memory model), or L (large memory 
model). 
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EM, 87 


GR 


SETUP uses the memory-model arguments and 
the floating-point-math argument (see below) that 
you give to determine which libraries to build. 
Combined libraries speed up the process of creat- 
ing programs; however, because you need a sep- 
arate library disk for each library that you create, 
type letters only for the memory models that you 
know you will use. (If you use more than one 
memory model, you may also want to use the 
uncombined libraries instead of taking up disk 
space for combined libraries; see Section 1.4 for 
more information.) 


Type either EM or 87 to tell SETUP how your 
programs will handle floating-point-math opera- 
tions: using software that emulates an 8087 or 
80287 coprocessor (EM) or using an actual copro- 
cessor (87). 


Generally, type EM for this argument, since pro- 
grams created within the QuickC environment use 
the emulator. 


If you develop programs that perform scientific, 
mathematical, or financial calculations with real 
numbers and that will always run on systems with 
coprocessors, rerun SETUP and type 87 for this 
argument. Typing 87 builds an additional library, 
which requires substantial disk space, but creating 
programs with this library makes them smaller and 
faster. 


@ 
Type GR if you want to include the QuickC 
graphics functions (described in Chapter 4 of this 
manual and in the Microsoft C Run-Time Library 
Reference) in the library that SETUP builds. This 
option makes the library approximately 50I¢ 
larger. If you do not give this option, graphics 
functions are not included. The QuickC compiler 
must be able to find the GRAPHICS.LIB library 
if your program uses QuickC graphics functions. 
See Section 1.5 for more information. 
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m= Example 
SETUP F B: M EM 


The command line above tells SETUP to build the appropriate library for 
the medium memory model and for the floating-point emulator, 
MLIBCE.LIB, on floppy-disk drive B. 


1.3.2.3 Building Libraries on a Floppy-Disk System 


After you press ENTER, SETUP begins to build and install libraries. 
SETUP installs one library per disk; it prompts you when to swap, in 
drives A and B, the required Libraries distribution disks, the disks on 
which you are installing new libraries, and your scratch disk. 


SETUP reads each memory-model argument (S, M, C, or L) and the 
floating-point-math argument (EM or 87) that you have given on the 
command line and builds one library for each possible combination of 
the two. SETUP displays the names of the libraries it is building as it 
builds them. 


SETUP also names the libraries it builds based on the memory model(s) 
and floating-point-math package(s) you choose. Each default library name 
has the following form: 


{S|M|C]|L}LIBC{E| 7}.LIB 


The first character of the library name is the same as the memory-model 
argument: S for the small (default) memory model, M for the medium 
memory model, C for the compact memory model, or L for the large 
memory model. The last character of the base name (the part of the name 
before the .LIB extension) is determined by the floating-point-math argu- 
ment: E if the EM argument was given or 7 if the 87 argument was given. 


For example, the library named MLIBCE.LIB supports the medium 
memory model and the emulator floating-point-math package, the defaults 
for the QuickC programming environment. The library named 
SLIBC7.LIB supports the small memory model and the 8087 /80287 
floating-point-math package, which can be used only for programs run on 

- machines with a math coprocessor. 


Note 


For ease of discussion, the remainder of this manual uses the default 
names to identify libraries that support particular combinations of 
memory models and math packages. 
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1.3.2.4 Setting Up the DOS Environment 
on a Floppy-Disk System 


The final step of installation is to set up the DOS environment so that 
QuickC can find the files that it needs. Type the following DOS com- 
mands: 


SET a 
SET LIB=A: 
SET INCLUDE=A: \INCLUDE; 


These commands tell QuickC to look for executable files and library files 
in the root directory of the disk on drive A and for the include files in the 
\INCLUDE directory of the disk in drive A. These settings hold until 
you next reboot your system. You may want to add these commands to 
your AUTOEXEC.BAT file so that — are carried out automatically 
when you reboot. 


Before you run QuickC, enter the following values in your CONFIG.SYS 
file, then reboot your system: 


files=15 
buf fers=10 


1.4 Using Uncombined Libraries 


The SETUP program builds combined libraries because creating pro- 
grams with uncombined libraries takes more time. If you use many dif- 
ferent combinations of memory models and floating-point-math packages, 
you may not want to use up the disk space required for all of the combined 
libraries you need. Instead, you may use the individual library compo- 
nents. Note that using uncombined libraries has the following disadvan- 
tages: 


e You must generally type longer command lines to compile and link 
programs. 


e You must tell the linker not to use the libraries it would normally 
use and explicitly give it the names of the appropriate uncombined 
libraries. 


e Linking with uncombined libraries takes longer than mane: with 
combined libraries. 
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The following uncombined libraries are provided with the Microsoft 
QuickC Compiler (where m indicates the appropriate memory model): 


Library Purpose 


mLIBC.LIB Standard run-time library; contains all of the rou- 
tines included in the Microsoft C run-time library 
except math routines that require floating-point 
support. 


mLIBFP.LIB Floating-point math library; required whenever 
your program uses EM.LIB or 87.LIB. 


EM.LIB Model-independent floating-point emulator; used 
to perform floating-point operations. 


LIBH.LIB Model-independent “compiler helper” functions; 
used to handle complex operations such as 32-bit 
multiplication and division. 


87.LIB Model-independent 8087 /80287 floating-point 
library; provides minimal floating-point support 
and can only be used when an 8087 or 80287 
coprocessor is present. 


The following list shows each combined library built by SETUP and the 
corresponding uncombined libraries: 


Combined Library Uncombined Libraries 

mLIBCE.LIB mLIBC.LIB, mLIBFP.LIB, LIBH.LIB, 
and EM.LIB 

mLIBC7.LIB mLIBC.LIB, mLIBFP.LIB, LIBH.LIB, 
and 87.LIB 


If you choose to use uncombined libraries, copy the uncombined libraries 
you need from your working copies of the Libraries #1, Libraries ##2, and 
Libraries #3 distribution disks to the subdirectory you created for 
libraries on your hard disk (by default, dest\ LIB). If you are running on a 
floppy-disk system, use your working copies of these distribution disks. 
The following list shows where to find each type of library: 


Libraries Distribution Disk 
Model Libraries #1 
independent 
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Medium and small _ Libraries #2 
model 


Compact and Libraries #3 
large model 


See Section 9.4.2.3 for more information about specifying uncombined 
libraries. 


1.5 Using the Microsoft C Graphics Library 


If you decided not to include graphics in the combined libraries built by 
SETUP, but you still want to use Microsoft C graphics routines in your 
programs, QuickC must be able to find the GRAPHICS.LIB library, 
which contains the graphics routines. This library is included on the 
Libraries #1 distribution disk in your package. If you installed QuickC on 
a hard-disk system, copy this library to the subdirectory where you told 
SETUP to install libraries. 


If you create a graphics program within the QuickC environment, set up a 
program list for that program as described in Section 6.2.6. Then add 
GRAPHICS.LIB to the program list as described in Section 6.2.7. 


If you create a graphics program outside the QuickC environment, you 
must link with GRAPHICS.LIB explicitly. You have the following 
choices: i 


e Specify GRAPHICS.LIB on the QCL or LINK command line as 
described in Section 9.4.2.3. 


e Specify GRAPHICS.LIB in the CL environment variable, as 
described in Section 9.3, or in the LINK environment variable, as 
described in Section 9.5. Specifying GRAPHICS.LIB in the DOS 
environment links your program with GRAPHICS.LIB automati- 
cally. 


1.6 If You Have a Mouse 


You can use QuickC with or without a mouse. Where appropriate, this 
manual describes procedures with the keyboard and with the mouse, so 
you can use either or both. 
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Note 


Microsoft QuickC is designed for use with the Microsoft Mouse. Many 
manufacturers advertise their pointing devices as being compatible 
with the Microsoft Mouse. QuickC may work with some of these de- 
vices if they are fully compatible, especially if they emulate the func- 
tion calls of the Microsoft Mouse. For details, check with your mouse 
manufacturer. 


The following mouse-specific terms are used in this manual: 


Term Definition 

Point Move the mouse until the pointer rests on what 
you want to point to. 

Press Hold down the mouse button. 

Click Quickly press and release the mouse button. Click 
refers to the left button unless otherwise indicated. 

Drag Hold down the left mouse button while moving the 
mouse across a flat surface, such as a desk top. 

Double click Click the left mouse button twice in rapid suc- 

- cession. 


1.7 Running the QuickC Compiler 


The following sections explain how to start and exit the Microsoft QuickC 
Compiler, gives steps for a sample compilation, and explains options that 
you can give on the QC command line to change its behavior on start-up. 


1.7.1 Starting the QuickC Compiler 


After you have installed the compiler software and set up your DOS envi- 
ronment variables, you are ready to start QuickC. Which of the following 
methods is used depends on whether you are using a hard-disk or a 
floppy-disk system: 
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e Ona hard-disk system, you can start the QuickC compiler from 
any directory, provided that you used NEW-VARS.BAT to set 
up the environment. Otherwise, execute the DOS CD command to 
move to the directory where you installed the QC.EXE file. Then 
simply type 


QC 


e Ona floppy-disk system, make drive B the current drive. Place 
your working copy of the Product distribution disk in drive A and 
the disk you will use for your programs in drive B. Start QuickC 
using the following command: 


A:QC 


When the QuickC screen appears, swap your working copy of the 
Work distribution disk in drive A. 


To load a C source file automatically when you start QuickC, type the file 
name after QC on the command line. The QuickC compiler also allows 
you to give a number of arguments and options on the command line; the 
following section describes these arguments. 


1.7.2 The QC Command 


With the QC command, you can control the operation of QuickC by using 
command-line options. These options can be given in any order, as long as 
the name of the source file you are loading is given last on the command 
line. Here is the full syntax: 


QC | [/b] [/sg] [/h] [/1 quecklib] [sourcefile] | 
The following list describes the available QC options: 


Option Effect 


/b Starts the Microsoft QuickC Compiler in black- 
and-white mode. Use this option if you are using a 
composite monitor on your system. 


/g Try this option if you are using a color graphics 
adapter (CGA). QuickC automatically adjusts the 
way it updates the screen to accommodate your 
hardware. On some machines it is possible to 
update the screen faster than the QuickC default. 
The /g option causes QuickC to update the screen 
as fast as possible. If you see “snow” (dots flicker- 
ing on the screen) when you update large areas of 
the screen (for example, with PGUP), then your 
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hardware cannot handle the speed and you should 
restart QuickC without the /g option. This option 
has no effect on machines with enhanced graphics 

(EGA) or monochrome adapter (MA) cards. 


Starts QuickC using as many lines as possible for 
the display adapter in use. For example, the IBM 
Enhanced Graphics Adapter (EGA) can display 43 
lines when attached to an IBM Enhanced Color 
Display. 


Type the name of a Quick library, if you want to 
load one. If your programs use C library routines 
that are not built into the QuickC programming 
environment, you can compile them faster by load- 
ing a Quick library containing these routines. (See 
Table 6.1 for a list of built-in C library routines 
and Section 10.1 for information about creating 
and using Quick libraries.) 


Type the name of a C source file if you want to 
load that file for editing or compiling when you 
start QuickC. 


1.7.3 Leaving QuickC 


To leave QuickC and return to the operating system, follow these steps: 


1. Type ALT+F to display the File menu. 
2. Type X to execute the Exit command. 


Other ways to leave QuickC are described in Chapter 6, “Creating and 


Saving Programs.” 


If you leave QuickC without writing your program to disk, a prompt asks 
if you want to save the program. Type the name you want to give the file, 


then press ENTER. 


1.7.4 Sample Compilation 


This sample compiling session will give you hands-on practice with 
QuickC. During this session, you will compile the demonstration program 
CFLOW.C, which outlines the function calls and dependencies in any C 


source file. 
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The steps below will take you through the compilation process: 
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1. 


10. 


11. 
12. 
13. 


If you have a hard-disk system, the CFLOW.C program is in the 
directory that SETUP created for sample programs (by default, 
dest\ BIN\SAMPLE). 


If you have a floppy-disk system, place your working copy of the 
Product distribution disk in drive A and your working copy of the 
Libraries #2 distribution disk in drive B. 


If you are running on a hard-disk system, type 


qc cflow.c 


and press ENTER to start QuickC and load CFLOW.C. If you are 
running on a floppy-disk system, type 


a:qce cflow.c 

and press ENTER. 

Press ALT+R to open the Run menu. 

Press C to execute the Compile command. 

A box (known as a “dialog box”) for the Compile... command 
appears. For now, just press ENTER. When QuickC has finished 
compiling your program, the Compile dialog box disappears from 
the screen. 

Press ALT+R to open the Run menu again. 


Press ALT+O to execute the Set Runtime Options command. 


A dialog box for the Set Runtime Options command appears. Type 
cflow.c in the Command Line text box and press ENTER. 


Press ALT+R to open the Run menu again. 


Press S to run your program. If it runs without errors, QuickC 
displays the following message: 


Program returned (0). Press any key 
Press any key to return to the QuickC view window. 
Press the ALT+F keys to open the File menu again. 


Press X to exit QuickC and return to DOS. 
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1.8 Saving Options: 
the QC.INI Initialization File 


QC.INI is the initialization file that QuickC uses to save settings for the 
Options... command on the View menu and the Compile... command on 
the Run menu. The Options... settings determine the colors used to dis- 
play different types of text, tab-stop indenting, and the presence of scroll 
bars in the windows. The Compile... settings control various aspects of the 
compilation process. 


If you have changed any of the Options... or Compile... settings when you 
exit from QuickC, these changes are written to a file named QC.INI. 
QC.INI is not supplied on any of the distribution disks. It is created only 
when changes are made to the View menu Options... settings. If you use 
only the default settings, QC.INI is never created. 


When QuickC starts, it looks for QC.INI first in the current directory, 
then in the directories given by the PATH environment variable. If 
QuickC does not find QC.INI, it uses the default View menu Options... 
settings. If you change the Options... settings, QuickC writes the new 
QC.INI file to the directory where it was originally found. 


Note that you can have multiple QC.INI files in separate directories; 
QuickC uses the version in the directory from which you start QuickC. 
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Introducing the QuickC Programming Environment 


This chapter introduces the QuickC programming environment. It 
describes the parts of the environment and shows how to perform common 
operations within the environment, including: opening menus and dialog 
boxes; choosing commands and options; and selecting and scrolling text. 


This chapter provides essential information if you want to experiment 


with the programming environment before learning in detail about the 
individual menus and commands in Part 2 of this manual. 


2.1 The QuickC Screen 


The mouse pointer appears 
only if you have a mouse. 


Watch expressions 


The caption bar 
displays the name of the 
file you are currently 


appear in the watch window. working on. Menu bar 
File Edit View Search Run Debug Calls Fl=Help 
x1: 8.765 
“UZ: 9.1414 
sum: 88.1244 


C:\SRC\dotprod.c 
scanf "ZF", Bul jl); 
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my ; 


float dot_product(v1, v2, n) 
float vif], v20I; 


int n; 
{ 
float sum = @.; | 
int i: 
for (i = @; i < ni itt) Z 
sum += Cvilil * v20il); ES 


printf("The dot product of the tuo above vectors is “%8.6f, A 


error C2@@81: (1 of S) 
newline in constant 


Context: <Program not compiled> 08619: B@1 


Current cursor 

position (row 

and column) 
Error window ° 


Program List: <None> 


Name of the 
current program 
list (or “<None>” 

if none is loaded) | 


Current program 
context 


Status line 
View window 


Scroll bars 


Figure 2.1 The QuickC Screen 
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! describes these components: 
Element 


Cursor 


Mouse pointer 


View window 


Menu bar 


Title bar 


Scroll bars 


Status line 
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Figure 2.1 illustrates the components of the QuickC screen. The list below 


Description 


A flashing underscore or block that shows 
where text you enter will appear on the 
screen. If QuickC is in insert mode, the cursor 
is a flashing underscore; if it is in overtype 
mode, the cursor is a flashing block. (See Sec- 
tion 7.1.2 for information about overtype 
mode.) 


A small rectangular block that appears in the 
center of the screen if you have a mouse 
installed. 


The area of the screen where you enter and 
edit the text of your program and trace 
through your program during debugging. 


The bar at the top of the screen that contains 
the names of the QuickC command menus. 


The bar below the menu bar that displays the 
name of the file being edited in the view win- 
dow. If no file is loaded, or if you are working 
on anew program, untitled.c appears in 
the title bar. 


Bars along the right and bottom margins of 
the screen that show your relative position in 
the file. If you have a mouse, scroll bars also 
give you a convenient way to move text up 
and down or right and left within the view 
window. Scroll bars can be toggled on and off 
through the View Options... dialog box. 


The last line on the screen showing current 
program list and the program context. If you 
have loaded a program list, Program List: 


_1s followed by the name of the program list. 
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Otherwise, Program List: is followed by 
<none>. (See Chapter 6, “Creating and Sav- 
ing Programs,” for a description of program 
lists.) If the program has not yet been com- 
piled, Context: is followed by Program 
not compiled. If the program has been 
compiled but is not being executed, Con- 
text: is followed by Program not run- 
ning. If you are running or stepping through 
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the program, the name of the current source 
file, followed by the the name of the function 
that is currently being executed, appears after 
Context:. On the far right, the current cur- 
sor position is displayed as a combination of 
line and column numbers. Just to the left of 
this cursor-position display, the letter C 
appears when the CAPS LOCK key is toggled 
on, and N appears when the NUMLOCK key is 
toggled on. 


Watch window A window that appears on the screen only 
when you are using the Add Watch... com- 
mand. See Section 8.2.3.1 for more informa- 
tion about the watch window and the Add 
Watch... command. 


Error window Appears on the screen only when your pro- 
gram causes compilation or run-time errors. 
See Section 5.5 for more information about 
the error window. 


2.2 Using QuickC Menus 


QuickC commands are organized in “menus” on the menu bar. A sample 
menu, File, is shown in Figure 2.2. 


Open... 

Open Last File FZ 
Merge... 

Save 

Save As... 


Set Program List... 
Clear Program List 
Edit Program List... 


Print... 
DOS Shell 
Exit 


Figure 2.2 Sample Menu 
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Commands followed by dots (. . .) prompt you for additional information 
when you select them. Commands without dots are executed as soon as 


you select them. 


2.2.1 Contents of QuickC Menus 


The following list describes the QuickC menus and the commands they 


contain: 


Menu 
File 


Edit 


View 


Search 


Run 


Debug 


Calls 


Help 


Actions of Commands 


Create, load, merge, print, or save source files. 
Other commands on this menu set up or edit the 
list of source files in a program, temporarily exit to 
DOS, and end the QuickC session. 


Delete, add, or copy source-file text. 


Customize the appearance of the QuickC program- 
ming environment and specify what QuickC 
displays. 


Find or replace text in source files, find functions 
during debugging, or display source-file lines that 
cause compilation errors. 


Compile and run programs and set compile-time 
and run-time options for programs. 


Control the use of debugging features such as 
watch expressions, breakpoints, and screen swap- 
ping. 

Does not contain commands. Instead, it shows the 
hierarchy of functions that have been called by 
other functions and allows you to move the cursor 
to the point where any of the displayed functions 
are called. 


Control the display of help information. The Help 
menu Is described in Section 2.6 of this manual, 
“Getting Help: the Help Menu.” 


2.2.2 Choosing Commands from Menus 


In the QuickC environment you have several ways to display menus and 
select commands. Use the method you find most convenient. 
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m Keyboard 
To select a command with the keyboard, perform the following steps: 


1. Press the ALT key plus the key with the first letter of the menu 
name. This opens the menu. 


2. Press the key corresponding to the highlighted or underlined letter 
in the command name. If a command is already highlighted, press 
ENTER to select it. 


A second way to select commands is the following: 


Press ALT. 


2. Move the highlight from command to command using the DIREC- 
TION keys. 


3. Press ENTER to carry out the highlighted command. 
To cancel any command before you carry it out, press ESC. 


Note that the ALT key is “sticky”: when pressed, it highlights the first 
entry in the menu bar, File. It is also a “toggle”: if you press the key 
again, its state is reversed. Therefore, if you press ALT+R, the Run menu 
opens. If you immediately press ALT again, the Run menu disappears, and 
the Run selection in the menu bar is highlighted. If you press ALT once 
more, the highlight disappears completely. 


If more than one command on a menu has the same first letter, one of 
those commands has a letter other than the first letter highlighted (indi- 
cated here in boldface). For example, on the File menu both the Open... 
-and the Open Last File commands begin with “O.” Press O to execute the 
Open... command, or press L to execute the Open Last File command. 
Pressing ESC turns off a menu display completely, whereas pressing ALT 
closes it but leaves the menu name selected. To open a menu and then 
open other menus on the menu bar, open a menu and then use the LEFT or 
RIGHT key to open either adjacent menu. 


m™ Mouse 


To choose a command with the mouse, click the menu name with the left 
mouse button. Then click the command with the left mouse button. 


To cancel a command with the mouse, click anything except a menu with 
the left mouse button. 
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2.2.3 Shortcut Keys for Commands 


A key name appears to the right of some menu commands, as shown in 
Figure 2.3. 


Shortcut keys 


Continue FS 
Compile... 


Set Runtime Options 


Figure 2.3 Shortcut Keys 


These are “shortcut keys.” Use the shortcut keys to carry out a command 
without first opening the menu and selecting the command. For example, 
simply press F2 to load the most recently edited file without having to 
open a menu. Table 2.1 lists the QuickC shortcut keys. 


Table 2.1 

QuickC Shortcut Keys 

Menu Command Key(s) 

File Open Last File F2 

Edit Undo ALT+BACKSPACE 
Cut SHIFT+DEL 
Copy CTRL+INS 
Paste SHIFT+INS 
Clear DEL 

View Output Screen F4 

Search Selected Text CTRL+\ 
Repeat Last Find — F3 
Next Error SHIFT+F3 
Previous Error SHIFT+F4 

Run Continue F5 


Debug Delete Last Watch SHIFT+F2 
. Toggle Breakpoint F9 
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2.3. Using Dialog Boxes 


QuickC displays a “dialog box” when it needs additional information or 
when it needs you to confirm an action you have chosen. The dialog box 
contains areas where you enter information, select options to commands, 
or activate controls to execute or cancel a command. While QuickC 
displays a dialog box, any input you type at the keyboard affects the item 
in the dialog box that has the “input focus.” The flashing underscore 
appears in the item that has the input focus. 


Many items in dialog boxes are options that you can turn on or off. To 
turn the option with the input focus on or off, press SPACEBAR. ‘To move 
the input focus to an option and turn it on or off in a single step, press ALT 
and type the highlighted letter in the option name. 


Clicking an item with the mouse affects it, regardless of the input focus. 


In this section, the Compile... and Open... dialog boxes shown in Figure 
2.4 are used as examples to illustrate the parts of a dialog box. 


Select only one from each Select any number of 
group of circular buttons. check boxes. 


Program List: |Lexer 
Current File: |C:\SRC\lexer.c 


Warning Levels \ Qutput Options Miscellaneous 
Obj Debug 
Memory Pointer Check 
Exe Stack Check 
Syntax Check Only Language Extensions 
Optimizations 


Build Program | Compile File Rebuild All 


Press ENTER from anywhere in the — |To choose a command button, 
dialog box to choose the command |move the input focus to that 
button with the input focus (double button and press SPACEBAR. 


outline). Type the text in a text box. 
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Type text in a text box. 


File Name: 


C:\SRC 


ons as1@~-Z.c asZ-1.c¢ asS-1i.c backw.c 
addvar.c as1@-3.c asZ-S.c asS-Z.c backwZ.c 
appl.c as1@-4.c as2Z-8.c asS-3.c bin_text.c 
array.c asi@-5.c as3-1.c as6-Z.c blank.c 
as1-3.c asl1-1.c as3-Z.c as6-4.c bomb.c 
asl-4.c as11-5.c as3-3.c as6-5.c bubsort.c 
as1@-1.c Pie: 3c cflou.c 


Press ENTER from 
anywhere in the 

' dialog box to choose 
the command button 
with the input focus 
(double outline). 


To choose a command button, 
‘move the input focus to that 
button and press SPACEBAR. 


Select items from a list box. 


Figure 2.4 Sample Dialog Boxes 


Dialog boxes contain some or all of the following elements: 
Element Description 


Text box A space in which to enter information for 


commands, such as a file name or text you are 


searching for. 


A text box has the input focus when a flash- 
ing underscore appears in the box. This indi- 


cates that you can enter or edit the text in 


the box. If you type more text than a text box 


can hold, the text box scrolls to the left to 
allow you more room to enter text. 


To correct typing errors in a text box, press 


BACKSPACE or use the QuickC editing keys 


described in Section 7.1.1. To move the input 
focus from the text box to the next or previ- 


ous item in the dialog box, press TAB or 
SHIFT+TAB, respectively. To move the input 


focus to any item in the dialog box, press ALT 


and type the highlighted letter in the item 
| name. 
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A box that lists the files matching the specifi- 
cation in a text box. List boxes give you an 
alternative way to select a file for a command: 
instead of typing the file name in the text 
box, you can select it from the file names 
listed in the list box. 


The file name with the input focus appears in 
reverse video. This file name is the currently 
selected file name. The currently selected file 
name also appears in the text box. To move 
the input focus to a different file name, press 
the DIRECTION keys or type the first character 
of the file name. To carry out the command 
by using the selected file name, press ENTER. 


Options preceded by opening and closing 
brackets (||), which let you select one or more 
options from a group of options. 


To move the input focus forward and back- 
ward between check boxes, press the TAB and 
SHIFT+TAB keys. 


To turn the check box with the input focus on 
or off, press SPACEBAR. When a check box is 
turned on (that is, selected), an X appears in 
the box. 


To turn any check box on or off, press ALT 
and type the highlighted letter in the option 
name. 


A square box with a label that indicates what 
choosing the button will do. 


When a command button has the input focus, 
it has a double outline. The command button 
with the input focus indicates the action car- 
ried out when you press ENTER or SPACEBAR. 
To move the input focus forward and back- 
ward between command buttons, press TAB 
and SHIFT+TAB, or press ALT and type the 
letter that is highlighted in the command box. 


To execute the command with the options 
you have chosen from the dialog box, press 
SPACEBAR or ENTER. After the command is 
executed, the dialog box disappears. 
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Circular buttons Options preceded by opening and closing 
parentheses ( () ), which indicate that you 
may select only one option from the group. 


To move the input focus forward and back- 
ward between circular buttons, press UP and 
DOWN. 


To turn the circular button with the input 
focus on or off, press SPACEBAR. When a circu- 
lar button is turned on (selected), a highlight 
appears inside of it. 


To turn any circular button on, press ALT and 
type the highlighted letter in the option 
name. 


After you have selected a circular button from 
a group of circular buttons, press TAB or 
SHIFT+TAB to move on. 


Often, a dialog box opens with options already chosen. These usually are 
the options that were chosen the last time the command was selected. For 
example, the Options... dialog box might open with the options set from 
the last time you changed them this session. 


To select a check box, circular button, or command button with the 
mouse, use these two steps: 


1. Point to the option. 
2. Click it with the left mouse button. 


2.4 Selecting Text 


When you work with the QuickC environment, you need to “select” the 
text that the next command or action will affect. 


m™ Keyboard 


To select text, either in a work area (for instance, a list window) or in a 
text box, hold down the SHIFT key while you press DIRECTION keys to move 
the cursor over the text you want to select. You can use different key com- 
binations to select more than one character of text at a time. These key 
combinations are listed in Table 7.1. 
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m@ Mouse 


To select text, point to the left of the text you want to select and drag the 
mouse pointer over the text. 


2.5 Scrolling 


Often, a program or procedure is too big to fit in the visible portion of a 
view window. To view information that won’t fit in the window, you can 
move the text up, down, right, or left. This is called “scrolling.” 


m@ Keyboard 


To scroll with the keyboard, once you have reached the last character on 
the screen, press the DIRECTION key for the direction you want to scroll. 
For example, to scroll right, go to the rightmost character on the screen 
and keep pressing the RIGHT key. To scroll more than one character at a 
time, refer to Table 2.2. 


Table 2.2 
Scrolling with the Keyboard 


To Scroll: Press: 


Down one screen PGDN 
Up one screen PGUP 
Left one screen CTRL+PGUP 
Right one screen CTRL+PGDN 


m Mouse 


If you have a mouse installed, you can use the scroll bars at the bottom 
and right margins of the active window to scroll text up, down, left, or 
right. 


To scroll with the mouse, point to the “scroll box” (the dark box on a 
scroll bar) and drag it to a position on the bar that corresponds to the 
general location you want. To scroll a page at a time, place the mouse 
pointer in the scroll bar between the scroll box and the top or bottom of 
the scroll bar, and click the left button. To scroll one line or one character 
at a time, click the arrows at either end of the scroll bars. 
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2.6 Getting Help: the Help Menu 


If you need information about QuickC editing keys or menus, C language 
features, or C library functions, QuickC makes it fast and easy to get help. 
You can tell QuickC to display help information about any C keyword or 
function name in the view window while you are editing your source file. 
Or, if you prefer, you can browse through a list of help topics to find the 
information you need. 


To see QuickC help information while no other help information is being 
displayed, press F1. The first panel of QuickC help information, a list of 
commonly used QuickC editing keys, appears over the view window. 

Use the commands on the Help menu to view information about the 


QuickC keyboard commands or about C statement and function syntax. 
Figure 2.5 shows the Help menu. 


06 The Help Menu 


Figure 2.5 The Help Menu 


The commands in the Help menu are described below: 


Command Action 


General... Displays information about using Help, and about 
the QuickC menu and keyboard commands. There 
are several panels of general information. Press N 
(next) and P (previous) to move between panels. 


Topic Displays information about a C keyword or func- 
tion. 
Close Help Removes the help information from your screen. 


It is faster to use the shortcut keys described in Table 2.3 instead of the 
menu to display help information. 
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Table 2.3 
Help Shortcut Keys 


Menu Command Shortcut Key 


General Fl 
Topic SHIFT+F1 
Close Help ESC 


For example, to display information about a C keyword or function, do 
the following: 


1. Place the cursor anywhere on the word (including the space after 
the last letter). 
2. Press SHIFT+F1 to display information about that keyword. 
If you press SHIFT+F1 while the cursor is not on a C keyword or function, a 
dialog box appears listing topics (in uppercase letters). To display infor- 
mation from this list of topics, do the following: 
1. Use the DIRECTION keys to select a topic. 


2. Press ENTER. A list of the functions related to that topic appears; 
proceed to step 3. 


3. Use the DIRECTION and ENTER keys as described in steps 1 and 2 to 
display information about any function listed under that topic. 


To return to your program, press ESC. 
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C Quick Start 


This chapter introduces the basics of the C programming language using a 
brief, outline format. It is designed to get you “up and running” with © as 
quickly as possible. 


It is assumed you are familiar with programming in Pascal or BASIC. If 
you are completely new to programming, you can use this chapter and one 
of the books listed below to learn computer programming and the C 
language. 


To speed your learning, each topic occupies only two pages. The topics are 
presented in order of increasing complexity and in the approximate order 
of their appearance in C programs. For example, the discussion of variable 
declarations precedes the discussion of conditional statements. 


Each section first defines and describes a topic (such as formatted I/O), 
then goes on to outline its operation. Each section ends with a C program 
or program segment that highlights the topic. 


= Further C Resources 


You may want to explore C further with one or more of the books listed 
below: 


Hancock, Les, and Morris Krieger. The C Primer, 2d ed. New York: 
McGraw-Hill, 1985. (A beginner’s guide to programming in the C 
language. ) 

Kochan, Stephen. Programming in C. Hasbrouck Heights, NJ: Hayden 


Book Company, Inc., 1983. (A more comprehensive introduction to C 
with some emphasis on the UNIX environment.) 


Plum, Thomas. Learning to Program in C. Cardiff, New Jersey: Plum 
Hall, Inc., 1983. (A widely used introductory college text on computer 
programming using the C language.) 


Schildt, Herbert. C Made Easy. Berkeley, CA: Osborne/McGraw-Hill, 
ae good introduction to C for the reader who already knows 
BASIC.) 


Waite, Mitchell, Stephen Prata, and Donald Martin. C Primer Plus. 
Indianapolis, IN: Howard W. Sams. Inc., 1984. (The best-selling intro- 
duction to the C language.) 
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3.1 The Structure of C Programs 


All C programs contain preprocessor directives, declarations, definitions, 
expressions, statements, and functions. 

m@ Preprocessor directive 

A preprocessor directive is a command to the C preprocessor (which is 
automatically invoked as the first step in compiling a program). The two 
most common preprocessor directives are the # define directive, which 
substitutes text for the specified identifier, and the #include directive, 
which includes the text of an external file into a program. 

m@ Declaration 

A declaration establishes the names and attributes of variables, functions, 
and types used in the program. Global variables are declared outside func- 
tions and are visible from the end of the declaration to the end of the file. 
A local variable is declared inside a function and is visible from the end of 
the declaration to the end of the function. 

H Definition 

A definition establishes the contents of a variable or function. A definition 
also allocates the storage needed for variables and functions. 

m Expression 

An expression is a combination of operators and operands that yields a 
single value. 


m Statement 


Statements control the flow or order of program execution in a C program. 


m Function 
A function is a collection of declarations, definitions, expressions, and 


statements that performs a specific task. Braces enclose the body of a 
function. Functions may not be nested in C. 
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@ main function 


All C programs must contain a function named main where program exe- 
cution begins. The braces that enclose the main function define the begin- 
ning and ending point of the program. 


m= Example: General C program structure 


/* preprocessor directives +/ 


#include <stdio.h> /* include standard C header file +/ 
#define PI 3.14 /* define symbolic constant +*/ 

float area; /* global declaration */ 

int square (int); /* function prototype */ 

main () 

{ /* beginning of main function 


and program */ 
int radius_squared; /* local declaration +/ 
int radius = 3; /* declaration and initialization +/ 


radius_squared = square (radius); /* pass a value 
to a function */ 


area = PI * radius_squared; /* assignment statement +/ 


printf ("area: %6.2f\n", area); 


} /* end of main function & program */ 
square (r) /* function head +/ 
int r_squared; /* declarations here are known only «/ 
/* to square x / 


r_squared =r * Yr; 


return (r_squared); /* return a value to calling statement x / 
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3.2 Declarations 


Declarations establish the names and types of variables, and the types of 
functions defined elsewhere. 


™@ Standard data types 


The C language defines a standard set of data types, including character 
(char), integral (int), and floating point (float). 


@ Declaring variables and functions 


Declare variables before using them in a C program. Variables do not 
have to be initialized, but you can give them initial values in definition 
statements. 


Functions can be declared explicitly in a function declaration before the 

definition of their contents. Functions with a return type other than int 

must be declared before using them. Without an explicit declaration, the 
first reference to a function will assume an int return. 


m Creating new type names 


Use the typedef declaration to create new type names for existing data 
types. The use of typedef declarations can make programs more portable 
and reliable. 


A defined type can serve as a reminder of the type of operations allowed 
with the variable (such as logical operations). Use the typedef keyword to 
shield programs against portability problems. Use a typedef declaration 
for data types that are machine dependent; only the typedef declaration 
will need to be changed when the program is moved. Finally, use the 
typedef keyword to provide better documentation for a program. A type 
called “employee” is easier to understand than one declared as a complex 
structure. A few typical typedef names and their associated meanings are 
shown below: 


typedef Name Meaning 

ulong Unsigned long integer 

bool Integer (tested for zero/non-zero conditions) 
string Pointer to character 
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m= @ Example: C declarations and defined types 


#include <stdio.h> 

typedef unsigned long ulong; /7/* programmer-defined types +/ 
typedef unsigned short ushort; 

typedef int bool; 

typedef char «string; 

/* typical function declaration: 


function name -- get_avg 
return value -- float 
expected parameters -- two integers 
*/ 
float get_avg (int, int); /* function prototype */ 
main () 
int matrix [3] [3]; /* 2-dimensional matrix declaration «/ 
struct date { /* structure declaration */ 
int month; 
int day; 
int year; 
3: 


/* once created, the typedef names can be used «/ 
bool true = 1; 

string example_string; 

example_string = "text"; 

printf ("string: %s\n",example_string); 

printf ("bool: %d\n",true) ; 
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3.3 Preprocessor Directives and Include Files 


External text files can be incorporated into a C program with the prepro- 
cessor #include directive. The preprocessor is automatically invoked as 
the first step of compilation. It interprets the preprocessor directives and 
then sends the modified C source file to the compiler. 


An # include directive instructs the preprocessor to substitute the con- 
tents of the external file for the line containing the directive. 


m C header files 


C header files are typically created to contain common variable and func- 
tion declarations. Such files can then be “included” into any source pro- 
gram that uses the variables or functions contained within it. External 
files that are to be used in #include directives are also known as 
“header” files and by convention have the DOS file-name extension .h. 


The # include directive is a command to the preprocessor. The # must 
be the first non-white-space character on the line. The line does not end 
with a semicolon. Generally, the # include directive usually appears at 
the beginning of the program file before the main function. 


Use a header file to store commonly used definitions and declarations or 
machine-specific constants in one place. This file simplifies the task of 
maintaining a set of declarations and definitions used by several source 
programs. The C run-time library functions use external files for their 
definition and declaration. Before using a library function, the appropriate 
external file should be included in the C program. 


= Controlling the include-file search path 


The format used for the header file specification in the #include directive 
determines the search path. 


Three possible formats are allowed: 


e Angle brackets specify that the current working directory is not 
initially searched. The search begins in the directories specified in 
the compiler command line and then continues in the standard 
directories specified in the include environment variable. Use angle 
brackets to specify header files supplied by the compiler. 
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e Double quotation marks specify that the file search begins in the 
directory in which the source file is found, then the directories 
specified on the compiler command line, and finally the standard 
directories. Use quotation marks to specify files supplied by the 
programmer. 


e An unambiguous path name given in either form (within quotation 
marks or brackets) specifies that only that path name will be 
searched. 


m@ Example: Including external files 


#include <stdio.h> /* standard C I/O header file -- 

look in standard directory +*/ 
#include <math.h> /* math functions header */ 
#include <graph.h> /* graphics header file */ 
#include "local.h" /* local header file -- 


look in directory where 
source code resides «/ 


#include "c:\test\math87.h" /* look for specified file only 
on disk drive C and only in 
subdirectory "test" +*/ 
main () 


+ 
/* body of C program +«/ 
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3.4 Variable Declarations 


Declare all variables before using them. Variables in C do not have to be 
initialized before use. Uninitialized variables contain values that are 
unpredictable. 


m Data types 


A declaration consists of a type specifier that is followed by a list of vari- 
ables having that type. Variables in a declaration list are separated by 
commas. 


m Scope 


The location of a variable’s declaration determines the scope (or visibility) 
of the variable. 


Global variables are declared outside of any function. A global variable 
can be accessed anywhere inside the source file in which it is declared. It is 
also accessible from other source modules. Global variables are generally 
declared at the beginning of the program text before the main function 
and after any # include directives. 


Local variables are declared within a function and are known only in the 
function where they are declared. Local variables are generally declared at 
the beginning of the function before any executable statements. 


m Storage requirements 


The storage requirements for the basic data types are shown below: 


Storage! 
Type (sytes) Range of Values! 


char 1 byte —128 to 127 

int sO ——- 

short 2 bytes —32,768 to 32,767 

long 4 bytes ~—2,147,482,648 to 2,147 482,647 
unsigned char 1 byte 0 to 255 

unsigned — — 

unsigned short 2 bytes 0 to 65,535 

unsigned long 4 bytes 0 to 4,294,967 ,295 

float 4 bytes + 3.4E-38 to 3.4E+38 

double 8 bytes + 1.7E-308 to 1.7E+308 


1Where storage or range of values are unspecified, they are implementation dependent. 
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The types int and unsigned are implementation dependent. For the 8086 
and 80286 family of machines, int is equivalent to short and unsigned is 
equivalent to unsigned short. 


= Register variables 


A register variable is an integer or pointer variable stored in a machine 
register. This storage speeds up programs by increasing the speed of 
variable access. If no machine registers are available, the declaration will 
be made but a register will not be used for storage. 


m Example: Variable Declarations 


#include <stdio.h> /* standard C header file */ 
float pi=3.14159; /* global declaration & initialization */ 


typedef unsigned short ushort; /* ushort is now a synonym 
: for unsigned short */ 


main () 
{ 
int i = O; /* local integer declaration 
and initialization +*/ 
ushort limit; /* variable limit is of type ushort, 
equivalent to unsigned short +*/ 
register int j; /* store variable j in machine register +*/ 


. /* body of the main function follows declarations +*/ 


} 
function1 () 
‘ int x=47; /* Integer declaration and initialization. 
x is “known" locally only in functionl */ 
- body of functionl follows declarations 
bs 
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3.5 Statements, Expressions, and Operators 


A C statement consists of program-control keywords (such as for or 
while), expressions, or function calls. An “expression” is a combination of 
operands and operators that yields a single value when evaluated. An 
“operator” specifies how its operands are to be manipulated. An “oper- 
and” is a constant or variable value manipulated in an expression. 


™ Statement format 

All statements end with a semicolon. Two or more statements can appear 
on one line, separated by semicolons. A null statement consists of a single 
semicolon. 

= Compound statements 

Compound statements are collections of other statements enclosed by 
braces ({ }). A compound statement can appear anywhere a simple C 

' statement appears. No semicolon occurs after the closing brace. A com- 
pound statement is also known as a “block.” 

m= Expressions 

An expression consists of an operator and its operands. An expression can 
occur wherever a value is allowed. Any expression terminated with a semi- 
colon is a statement. In C, assignments are considered to be expressions. 
@ Assignment operation 

An assignment operation specifies that the value of the right-hand operand 
is to be placed in the storage location specified by the left-hand operand. 
= Operators 

C contains more than 40 operators covering the range from the basic 
arithmetic operations to logical and bitwise operations. C operators 
produce a result that can be nested inside a larger expression. Operators 
can also be combined with the assignment operator (=) to form a 


compound assignment operator of the following form: 


x += y; 
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m Type conversions 


Explicit type conversions can be made with a “cast” or “coercion” 
operation that consists of a type enclosed in parentheses. The example 
below coerces the variable i (previously declared to be int) to be of type 
float: 


(float) i 


m™ Increment and decrement operators 


Use the increment operator (++) and the decrement operator (— —) to 
increment and decrement variables, respectively. Use these operators in 
either the prefixed or postfixed position. In the prefix form, the operand is 
incremented or decremented and its new value is the result of the expres- 
sion. In the postfix form, the immediate result of the expression is the 
value of the operand before it is incremented or decremented. In use, these 
operate as shown below: 


if (i-- > O) /* compare i to zero then decrement i */ 
printf ("compared then decremented") ; 
AE. (Sea oO) /* decrement i and then compare to zero */ 


printf ("decremented then compared") ; 


m Examples: Annotated C expressions 
while ((c = getchar()) != EOF) 


The example above, a nested expression, calls the getchar function, which 
returns an integer. It then stores the result in the variable c, then com- 
pares cto the constant EOF, which gives either a true or false value. 
This value determines whether the body of the while loop will be 
executed. 


The multiple assignment statement above stores the value 7 in b, then 
stores the contents of b (which is7)in a. 


x += 7; 
a <<= b; 


The first compound statement above increments x by 7. The second 
compound statement shifts a left by b bits. 
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3.6 Function Declaration and Definition 


A function declaration establishes the attributes (such as name, arguments 
expected, and return type) of a function. A function definition specifies the 
actual content of a function. 


@ Function declaration 


A function declaration consists of a return type, the function name, and 
optionally an argument-type list. It declares the characteristics of the 
function but does not define its contents. Functions can be declared 
implicitly or with a forward declaration. An implicit declaration occurs 
whenever a function is called without a prior declaration or definition of 
the function. An explicit function declaration (“forward declaration” ) 
consists of the function declaration and it makes known the characteristics 
of a function before it is defined or used. 


@ Function definition 


A function definition contains a function header and a function body. A 
function header consists of the type of data returned by the function, 
followed by the function name and a list of the function’s formal para- 
meters. The function body consists of local declarations and a compound 
statement (or “block”) that specifies what the function does. 


= §6©6©Return types 


The return type specifies what type of data the function returns. The 
return type is any fundamental, structure, or union type except an array 
or a function; the void type specifies that a function does not return any 
value. The default function-return type is int. You should not write func- 
tions that have structure or union return types. The large size of these 
objects will result in poor program performance. 


m Argument-type list and function prototypes 


A function declaration’s argument-type list specifies the types of argu- 
ments to the function. The use of argument-type lists is also known as 
“function prototyping.” The argument-type list contains one or more type 
names that specify the types expected for each argument. Use the type 
name void to specify that a function does not accept arguments. 
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= Formal parameters 


The formal parameters of a function declaration are variables that receive 
the values of arguments passed to the function. 


m Passing arguments to functions 


All arguments (except arrays) are passed by value. That is, a copy of the 
argument (not its address) is passed to the function. Asa result, a C 
function does not alter the contents of a variable passed to it. The only 
variation to the pass-by-value rule occurs when the argument passed to 
the function is an address. Here, the pointer indirectly allows the function 
to alter the contents of a variable with the given address. 


m@ Example: Function declaration and definition 


#include <stdio.h> /*x standard function declarations */ 
#include <stdlib.h> /* contains atof prototype declaration */ 
typedef char *string; 

main () 


string ascii_number; 

float float_number; 

ascii_number = "-6.02E-23"; 

printf ("string: %s\n", ascii_number) ; 

/* the next line generates a compiler warning message */ 
float_number = atof(); /* too few arguments */ 
float_number = atof (ascii_number):;:/+* correct call */ 
printf ("number: %e\n", float_number) ; 


} 


The C program above shows how the use of function prototypes can warn 
you of incorrect function calls. 


The function atof converts a character string to a floating-point number. 


The function prototype contained in the file stdlib.h specifies that the 
function expects one argument. 
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3.7 Looping Statements 


The for and while statements provide looping capabilities in C so that 
you can repeatedly execute statements. 


m The for statement 


Use the for statement to repeat a statement or compound statement a 
specified number of times. It consists of three parts: 


A loop-initialization expression (init-expr) 
2. A test expression (cond-expr) evaluated before each iteration 


3. A loop expression (loop-ezpr) executed at the end of each iteration 
of the loop 


Its format is shown below: 


for ([init-expr]; [cond-expr]; [loop-ezxpr]) 
statement 


First, init-expr is evaluated. Then, while cond-ezpr evaluates to a nonzero 
value, statement is executed. At the end of the loop, loop-expr is evaluated. 
When cond-ezpr becomes 0, control passes to the statement following the 
body of the for loop. 


Each expression in the for loop can be any valid C expression. Any or all 
of the three expressions can be omitted. If omitted, the semicolons must 
remain. Multiple expressions can be put within the parts of the for state- 
ment by separating the multiple statements from one another with com- 
mas. A typical use of multiple statements would be the initialization of 
several values in the ¢nzé-expr portion of the for loop, as shown below: 


for (i=1, j=l; i<= 100; i++) /* initialize i and j +/ 


mg The while statement 

The while loop consists of a test expression (test-ezpr) that is evaluated 
before the body of the loop is executed. If test-ezpr is false, the loop is 
never executed. The format of the while statement is: 


while ({[test-expr]) 
statement 
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The body of a while loop consists of a statement or a compound state- 
ment. If the test expression is true, the body of the loop is executed until 
the expression becomes false. 


m@ Ending the for or while statement 


The for and while statements normally end when the test expression in 
the loop becomes false. Use the break, goto, or return statement when- 
ever it 1s necessary to exit a loop early. 


Use the continue statement to terminate an iteration without exiting the 
loop. The continue statement passes control to the next iteration of the 
for or while statement. 


m =Example: Using for and while loops 


#include <stdio.h> 
main () 


int i, done; 
printf ("table of squares (every sixth number)\n"); 
printf ("\nfor loop\n"); 
printf ("number\t\tsquare\n") ;: 
for (i=O; i<= 20; i+=6) 
printf ("%d\t\t%d\n",i, isi); 
printf ("\nwhile loop\n"); 
printf (' 'number\t\tsquare\n" io 


i= 0; 

while (i <= 20) 
printf C'ZANC\ EVAN" a Lei) 
i +=" 63 


printf ("\nwhile (nonzero test expression version) \n"); 
printf ("“number\t\tsquare\n") ; 


i=0O; 
done = O; 
while (!done) { /* will execute until done = 1 +«/ 
printf ('JONENEV Nn" 5 Aa) 
i += 6; 
if (i > 20) 
done = 1; 
- 


J 


The program above uses for and while loops to calculate a table of 
squares for every sixth number between 0 and 20. 


59 


Microsoft QuickC Compiler Programmer’s Guide 


3.8 Conditional and Branching Statements 


The if and switch statements provide conditional and branching 
capabilities in C. 


= The if statement 


If the test expression in an if statement is true, the body of the if 
statement executes. Otherwise, the program continues with the next 
statement. An if statement can have an else clause. However, because C 
does not offer an “else if” clause, use nested if statements to accomplish 
the same effect. Without explicit direction, C pairs each else with the 
most recent if that lacks an else. Group statements between braces to 
make your intention clear to the compiler. Typical if statements are 
shown below: 


if (x < 0) 

printf ("Square root operation invalid\n"): 
if (x >= 0) 

4 


answer = sqrt (x); 
printf ("square root is: %6.2f\n", answer); 


= The switch statement 


The switch statement takes the place of a large number of nested if and 
else clauses. The switch statement transfers control to a statement 
within its body. The statement receiving control is the statement whose 
case constant expression (an integer or character constant, or a constant 
expression) matches the value of the switch test expression. Execution 
begins at the selected statement and continues through the end of the 
body or until a statement transfers control out of the switch body. Use 
the break statement to end processing of a particular case within the 
switch statement.Without the break, the program falls through to the 
next case. 


A default statement executes if there is no matching case constant 

expression for the switch test expression. If the default statement is 

omitted and no matching case is found, none of the statements in the 

switch body is executed. No two case constants within the same switch 

oe can have the same value. A sample switch statement is shown 
elow: 
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switch (i) { 


case 1: 

printf ("number 1\n"); 

break; /* continues after closing brace +*/ 
case 2: 
case 4: 


printf ("even\n"); /+* executes if i==2 or i==4 */ 

break; /* continues after closing brace */ 
default: 

/* prints if i not equal to 1, 2 or 4 +/ 

printf ("number not in our test list\n"); 


m Example: Using if and switch statements 


#include <stdio.h> 

#include <ctype.h> /* necessary with conversion function 
toupper */ 

main () 


char response [10]; 
char test_char:; 


printf ("Please enter your response (yes/no/quit): "); 
scanf ("%s", response); /* formatted input into a string */ 
if (toupper (response[0]) == 'Q') { /* test for q */ 
printf ("program exit\n"); /* execute if equal to q */ 
exit(1); 
switch (response[0]) { /* switch based on first character +*/ 
case 'y': /* multiple case labels */ 
case 'n': 
printf ("lowercase y or n as first letter\n"); 
break; 
default: 
printf ("not a lowercase y or n as first letter\n"); 
break; 
F 
test_char = toupper (response [0]); /* convert to uppercase */ 
switch (test_char) { 
case 'Y': 
printf ("Response is yes\n"); 
break; 
case 'N': 
printf ("Response is no\n"); 
break; 
default: 
printf ("Please enter a yes or no\n"); 
as 
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3.9 Arrays and Strings 


An “array” is a collection of data elements of a single type. A “string” is 
an array of characters that is terminated with the null character (’\0’). 


m Array types 


The base type of the elements of an array determines the array’s type. The 
base type of an array can be any valid C type, including so-called “aggre- 
gate” or constructed types such as structures. 


m Array storage 


The elements of an array are stored in contiguous memory locations and 
with increasing memory address from first element to last. Arrays aré 
stored by row. (That is, all of the columns of the first row are stored, then 
the columns of the second row, and so on.) An array name without brac- 
kets is a pointer to the first element of the array. The initial element of an 
array has a subscript of 0. 


m Strings 


A string in C is an array of characters that terminates with the null 
character (’\0’). Arrays representing strings must allow space for the 
storage of the final null character. 


m 6©Passing arrays to functions 


When an array is passed to a function, only the address of the initial 
element of the array is passed to the function. Omit dimensions when 
declaring arrays as parameters being passed into a function since the 
function needs to know only the starting address of the array. Since an 
address is passed to the function, the function can alter the contents of the 
array. 
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m@ Example: Using arrays 


#include <stdio.h> /* standard header file +*/ 
typedef char * string; /7* rename a 'char' type to string +*/ 
int strlen (string): /* function prototype */ 


/* declare & initialize test character array (string) */ 
char test_string [] = "This is a C string"; 
main () 
int x; 
x = strlenl (test_string); 
printf ("length (array method): %d\n",x); 
/* array & subscript version of strlen «*/ 


strlenl (s) 


char s[]; 
int i = 0; 
while (s{i] != '\0O') 
itt: 


return (i); 


The program above finds the length of a string by counting the characters 
in the string until it finds the terminating null character. 
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3.10 Introducing Pointers 


A pointer is a variable that contains the machine address of a variable, 
rather than the data itself. Use pointers to create and manipulate data 
structures, to allocate memory dynamically, and to provide pass-by- 
reference function calls. 


m™ §€©Creating pointers 


A pointer can point to an object of any type, including aggregate types 
such as structures, or even to a function. Declare a pointer by preceding 
the name of the object with the indirection operator (*), which means 
“pointer-to.” A pointer always points to an object of a particular type 
(that is, it contains the address of a value of a particular type). Initialize 
pointers before you use them because values contained in uninitialized 
pointers are unpredictable and likely to cause program problems. Some 
examples of pointer declarations appear below: 


int * intptr; /* pointer to int */ 

char * name; /* pointer to char +*/ 

™ Pointer storage requirements 

The amount of storage required for a pointer is the number of bytes re- 
quired to specify a machine address. On the 8086 family of machines a 
near pointer requires 16 bits and a far pointer requires 32 bits of storage. 


= Pointer operators 


The asterisk symbol (*) is the indirection operator and denotes “the data 
being pointed to.” 


The ampersand symbol (&) is the address-of operator. When an object is 
preceded by the address-of operator, the expression evaluates to the ad- 
dress at which the object is stored. 


m= Pointers and functions 


Pointers provide pass-by-reference function arguments. When arrays are 
passed to functions, only the address of the initial element is passed. 
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™ Pointer manipulations 


Only certain operations are valid with pointers: adding a pointer and an 
integer (incrementing a pointer); subtracting an integer from a pointer 
(decrementing a Sointen) subtracting two pointers (calculating the 
number of elements between them); and comparing two pointers. 


Whenever a pointer is incremented or decremented by an int-type unit, 
C scales the value of the int by the size of the object pointed to. This 
ensures that an increment of one, for example, will always point to the 
next data item regardless of the size of the item. 


m Examples: String-length functions using pointers 


/* pointer-incrementing version of strlen +#/ 
strlenl (s) 


char *s; 
a 
inti: 
for (i=O; *s != '\O'; st++) /* increment pointer variable s */ 
itt: : 


return (i); 


/* pointer-subtraction version of strlen */ 
strlen2 (s) 


char *s; 
{ 
char *p = s; /* set p to point to first character of s */ 
while (*p != '\O‘') 
ptt; /* advance to next character */ 


return (p-s); 


The two functions above can be substituted for the string-length function 
found in Section 3.9, “Arrays and Strings.” Instead of an array, these two 
functions use pointer manipulations to determine the length of a string 
passed to the function. 
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3.11 Pointers to Functions 


A pointer variable can be declared to point to any complex object, 
including a structure or a function. Use pointers to functions to create 
“veneric” functions that manipulate data of any type. 


m Creating pointers to functions 
Declare a pointer to a function as shown below: 
int (*number_compare) ():; 


The type of the variable number_compare is “pointer to a function that 
returns an integer.” The parentheses around *number_compare are 
required. Without them, the C language would use its precedence rules to 
interpret the line as a declaration of a function that returns a pointer to 
an int item—not the same thing at all. 


= Using pointers to functions 


The most common use of pointers to functions is passing them as argu- 
ments to other functions. The C library function qsort, for example, 
performs a “quick sort” on an array of data elements. This function takes 
as one of its arguments a pointer to a function that performs the actual 
comparison of the elements of the array. The comparison function can 
contain a comparison operation on any type. As a result, qsort can be 
used to sort an array of any type. The actual comparison is made by the 
user-supphed function and not by qsort. 


Use only the assignment, comparison, and indirection operators with 
function pointers; all other operations are undefined. 


m= Example: Creating a generic function using pointers 


The example program below uses a pointer to a function to build a generic 
comparison function. The function compare is passed a parameter that 
is a pointer to the appropriate comparison function (string or numeric). 
Once this information is passed into compare, the appropriate compar- 
son is made and the result printed out. 
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#include <stdio.h> 
#include <ctype.h> 
main () 
* 
int number_compare (): 
int string_compare (); 
char s1[80], s2[80]:; 
printf ("generic test for equality\n"); 
printf ("enter first item:\n"); 
gets (sl); 
printf ("enter second item:\n"); 
gets (s2): 
if (isalpha (+*s1)) 
compare (sl, s2, string _compare); /* pass address +/ 
else 
compare (sl, s2, number_compare); /* pass address +/ 


} 


compare (a, b, compare_function) 
char *a, *b; 
/* pointer to function that returns an int values/ 
int (*compare_function) (): 
{ 
/* use indirection operator 
to invoke correct compare function +*/ 
if ((*compare_function) (a,b)) 
printf ("equal\n");: 
else 
printf ("not equal\n"); 
: 
number_compare (a,b) 
char *a, *b; 


if (atoi (a) == atoi(b)) 
return (1); 
else 


return (0); 
} 
string_compare (a,b) 
char *a, *b; 


{ 
if (strcmp (a,b) ) 
return (0); 
else 
return (1); 
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3.12 Structures 


A “structure” is a collection of data elements of different types that are 
logically related. 


m Creating structures 


When you define a structure data type, the definition specifies the ele- 
ments and data types of the structure and creates a structure data type. 
The individual variables within the structure are called “members,” and 
the name of the structure is called the structure “tag.” A structure data 
type is defined by a declaration of the form: 


struct structure-name { 
member-declarations 


A date structure type, for example, is created with the following 
definition: 


struct date 


int month; 
int day; 
int year; 


¢ 


After a structure data type has been defined, you can declare a variable to 
be of the defined type. The structure tag must be preceded by the keyword 
struct. The declaration below defines a variable todays_date to be of 
type struct date: 


struct date todays_date; 


@ Variables within structures 


A variable that is an element of a structure type can be used just like any 
other variable. The member-of operator (.) specifies the name of the struc- 
ture member and the structure of which it is a member. The variable 
month within the structure variable todays_date is given the value 12 
by the assignment shown below: 


todays_date.month = 12; 
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= Structures and pointers 


Pointers to structures can be declared, as can pointers to any other data 
type. C uses a special symbol (—>) to refer to the member of a structure 
pointed to by a pointer. 


= Operations with structures 
Only three operations are allowed with a structure variable: you may take 
its address with the address-of operator (&); you may access one of its 


members; and you may assign one structure to another with the assign- 
ment operator. 


m= Example: Using structures 


+#include <stdio.h> 
#include <time.h> 


main () 
struct tm x*xcurrent_time:; 
time_t long_time; /* time value +/ 
time (&long_time) ; /* get number of seconds into long_time +/ 


/* convert to time structure */ 

current_time = localtime (&long_time) ; 

/* use member-selection operator to access 
individual element of structure */ 

printf ("hour: %d\n", current_time->tm_hour) ; 


} 


The program above uses the member-selection operator to access indi- 
vidual elements of the structure tm, which contains time information. It 
then prints the current value of the hour. 


The function localtime is not contained in the core of QuickC library 
routines. As a result, you will need to use the program list feature of the 
QuickC environment to compile this program. See Section 6.1 for details 
on using program lists. 
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3.13 Using C Input/Output Functions 


The standard C run-time library provides a complete set of input and 
output (I/O) functions for the C programmer. 


m™ Single-character I/O—getchar and putchar 


The getchar function “gets” the next character from the keyboard and 
returns it as the function’s value. The putchar function “puts” a 
character to the screen. 


# Formatted output—printf 


The printf function prints formatted output on the screen. The argu- 

ments to printf comprise a format string enclosed within double quo- 

tation marks, followed by a list of variable names, if any, that are to be 

printed. Literal text within the format string is printed as it appears in the 

string. Escape sequences within the format string insert special characters 

te the output. The more commonly used escape sequences are listed 
elow: 


Escape 

Sequence Character 

\n New line 

\t Tab 

AC Single quotation mark 
\" Double quotation mark 
\X Backslash 


@ Formatted input—scanf 


The scanf function reads formatted input from the keyboard. The 
arguments to scanf comprise a format string enclosed within double 
quotation marks, followed by a list of variable names to be read. The 
arguments used in the scanf function must be pointers to variables and 
not the variables themselves. This is required so that the scanf function 
can alter the variable’s contents. 
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= Format string specifications 


Conversion specifications mark the place within a control string where 
variable contents are to be printed or read. The first variable corresponds 
with the location of the first percent-sign symbol (%) and so on through 
the list of conversion characters. The following list shows the most 
common conversion specifications: 


Conversion 

Specification Meaning 

%d Decimal notation 

Zu Unsigned decimal notation 

%o Unsigned octal notation 

%x Unsigned hexadecimal notation 
%e Exponential notation 

%t Floating-point notation 

%c Single character 

%s String 


m= Example: Using the C I/O functions 


#include <stdio.h> 
typedef char * string; 
main () 


char c, j; 
LAG 23 
string item1[10], item2[10]; 
float x; 
printf ("please enter a single character:\n"); 
c = getchar (); 
printf ("\tthe character just input was -- %c\n",c); 
printf ("\nenter a digit, a string, a float, and a string: 
scanf ("%d %s ZF %¥s", &i, iteml, &x, item2); 
printf ("\n\ayou entered\n"); 
printf ("Y%d\n%s\n%f\n%s", i, iteml, x, item2); 
printf ("\n\nexample of conversion specifications:\n"); 
printf ("“decimal\toctal\thex\tcharacter\n") ; 
for (j = 65; j<=70; j++) 
printf ("Zd\tZo\tZ%x\tZe\n", j,5,5.5): 
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3.14 Using File I/O Functions 


The standard C run-time library provides a complete set of file input and 
output functions for the C programmer. 


= The FILE structure 


The standard I/O header file stdio.h contains the definition of a structure 
called FILE that determines the internal character of a file. 


@ Opening and closing files 


Before a file can be used, it must be opened by the standard library 
function fopen. After use, it should be closed by the library function 
fclose. 


The function fopen takes an external DOS file name and returns a file 
pointer used in later calls to file I/O functions. The file pointer is a pointer 
to a structure of type FILE. An fopen function call also specifies the 
mode of the file — read, write, or append. 


If you attempt to open, for writing or appending, a file that does not exist, 
it is created, if possible. If an error occurs when opening a file, fopen 
returns the null pointer value NULL. 


Use the function felose to close a file safely before you exit the program. 


m Single character file I/O—fputchar and fgetchar 


The fputchar function puts a character into the specified file. The 
fgetchar function gets a character from the specified file. A return value 
of EOF indicates that an attempt was made to read past the end-of-file. 


m Formatted file I[/O—fprintf and fscanf 


The fprintf function prints formatted output to the specified file. Its 
formatting is controlled by a format string that operates like the format 
string for the printf function. 


The fscanf function reads formatted input from the specified file with the 
same format string features that are used with the scanf function. A 
return value of EOF indicates that an attempt was made to read past the 


end-of-file. 
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Example: Using C file I/O 


#include <stdio.h> 
#include <ctype.h> 
main () 


{ 


FILE *fopen(), *fp_in, *fp_out; 
char fn_in[12], fn_out[12]; /* allow room for filename.ext */ 


printf ("enter name of input file: "); 


scant ("Ys"; £n_im): 
printf ("enter name of output file: "); 
scanf ("%s", fn_out); 


fp_out = fopen (fn_out, "w"); 
fp_in = fopen (fn_in,"r"); 
/* check for nonexistent input file; exit if fopen failed */ 
if (fp_in == NULL) { 
printf ("No input file %s\n",fn_in); 
exit. (1); 


/* if fopen is OK then execute the rest of the program +/ 
convert_file(fp_in, fp_out) ; 

printf ("\nFile %s cleaned up\n", fn_in); 

printf ("Output in file: %s\n", fn_out); 

fclose (fp_in); 

fclose (fp_out):; 

return (0); 


convert_file (input, output) 
FILE *input, *output; 


A 


} 


int ic; 
/* get characters until EOF */ 
while ((c = getc (input)) != EOF){ 
if (isupper (c)) /* convert case */ 
c = tolower (c); 
else 
c = toupper ({c); 
fputc(c,output); /* print it to the output file */ 
Bs 


The program above changes the case of all the characters within a file. 
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3.15 Accessing Command-Line 
Arguments in C 


Command-line arguments in C provide a way of passing arguments to a 
program when it begins execution. 


™ Basics of command-line arguments 


In the DOS environment, any information listed after the program’s name 
is known as a command- line argument. The C language provides a 
mechanism for accessing these arguments. The main function accesses the 
command-line arguments with two parameters. The arguments are listed 
below with a brief description of their contents: 


Argument Description 


argc The “argument count” is the number of 
command-line arguments. The final argument is 
given by argv[argc-1] since C arrays start 
with a zero subscript. 


argu The “argument vector” is a pointer to an array of 
character strings that contain the command-line 
arguments, one per string. 


m= Using command-line arguments 
The easiest way to learn about command-line arguments is to see a simple 
program using this feature. The program below prints out the number of 


arguments and the contents of the argument vector: 


#include <stdio.h> 


main (argc, argv) /*main function 
using command-line arguments:s/ 
char *argv[]; /* argument vector *«/ 
int argc; /* argument count */ 
int. i; 
printf ("arge: %d\n", argc): /* print no. of arguments +/ 
for (i = O; i < arge; itt) /* print argument contents +*/ 


printf ("argv [%d]: %s\n", i, argv[i]): 
} ; 


Remember to specify a few command-line arguments with the Set Runtime 
Options item from the Run menu when you create and run this program. 
Also note that in DOS versions prior to 3.0, the value of argv[0] contains 
the string “C,” not the name of the program. 
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m@ Using DOS wild-card characters 


Normal compilation produces a program that does not recognize the DOS 
file-name wild-card characters (* and ?). Link your program’s object file 
with the appropriate mMSETARGV.OBBJ file (the m refers to the memory 
model) to use DOS file-name wild cards. 


When the wild-card file name is expanded, all files that match the name 
are passed into the program. If no matches are found, the argument is 
passed literally. 


m Example: Command-line processing 


#include <stdio.h> 
#include <ctype.h> 
main (argc, argv) 
char t*argv[{]; 
int argc; 
{ 
FILE *fopen(), *fp_in, +*fp_out; 
/* check for aes number of arguments */ 
if (arge != 3) { 
printf ("correct usage is:\n"): 
printf (“convcase input-file output-file\n"); 
exit (0); 
} 
fp_out = fopen (argv[2], "w"); 
fp_in = fopen (argv[li], i ry 
/* check for nonexistent input file; exit if fopen failed +*/ 
if (fp_in == NULL) { 
printf ("input file error : %s\n",argv[1]); 
exit (1); 


/* if fopen is OK then execute the rest of the program */ 
convert_file(fp_in, fp_out); 

printf ("\nFile %s converted\n",argv[1]):; 

printf ("Output in file: %s\n",argv[2]});: 

fclose (fp_in); 

fclose (fp_out); 

return (1); 


convert_file (input, output) 


/* 
The contents of the convert_file function 
are the same as in Section 3.14 


*/ 
Bs 


The program above is a modification of the example program in Section 
3.14, “Using File 1/O Functions.” It accepts the names of the files as 
command-line arguments, with the input file name preceding the output 
file name. 
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Graphics Quick Start 


This chapter briefly outlines the fundamentals of graphics programming. 
It is designed to quickly give you the basic foundation for any graphics 
project you can design. 


To speed your learning, each topic occupies only two pages. The topics are 
presented in order of increasing complexity and in the approximate order 
of their appearance in graphics programs. 


Each section first defines and describes a topic (such as video mode), then 
goes on to outline its operation. Each section ends with a graphics pro- 
gram or program segment that highlights the topic. 


Important 


To run the graphics examples shown in this chapter, your computer 
must have graphics capability. This may be either built in or in the 
form of a graphics adapter card and a video display (either mono- 
chrome or color) that supports pixel-based graphics. 


You must include the graphics library in your program list to make an 
executable C program. The details of this process are in Section 6.1. 


= Further Graphics Resources 


You may want to explore microcomputer graphics further with one or 
more of the references listed below: 


Artwick, Bruce. Microcomputer Displays, Graphics, and Animation. 
Englewood Cliffs, NJ: Prentice-Hall, Inc., 1985. (Discussion of micro- 
computer graphics and animation from the creator of Flight Simula- 
tor. 


Cockerham, John T. “The EGA Standard.” PC Tech Journal 4:10 
(October 1986): 48-79. (Discussion of the EGA.) 


Hummel, Robert L. “Get the Full EGA Color Spectrum.” PC Magazine 
(June 23, 1987): 311-328. (Discussion of EGA color palettes.) 


International Business Machines. Enhanced Graphics Adapter (manual 
part # 6280131). (The official technical reference to the EGA; avail- 
able from IBM, 1-800-426-7282.) 


Norton, Peter. The Peter Norton Programmer’s Guide to the IBM PC. 
Redmond, WA: Microsoft Press, 1985. (The standard guide to the 
“inside” of the IBM PC family of computers. Several chapters devoted 
to video modes, with the exception of the EGA and VGA modes.) 
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4.1 Structure of a Graphics Program 


All graphics programs follow these five basic steps: 


1. Include the graphics library. 

Set the video mode. 

Determine the video-configuration parameters. 

Create and manipulate graphic figures. 

Restore the initial configuration before exiting the program. 


eS ae 


m Include the graphics library 


The include file graph.h defines the variables, function prototypes, and 
manifest constants used in graphics programming. Include this file in all 
programs that use the graphics routines. 


m Set the video mode 


The first step in a graphics program is to set a video mode that allows 
graphics operations. Ten graphics modes are supported in the C graphics 
library. These are listed in Section 4.2. 


The process of setting the video mode is shown below: 


1. Set the highest-level video mode needed for the program. Check 
the return value for failure. 


2. If you are unable to set the initial video mode, continue the at- 
tempt with less demanding modes until a mode can be set or until 
there is no mode of sufficient resolution for the program. If no valid 
video mode is found, return from the function and print an error 
message. 


= Determine the video configuration 
Call the _ getvideoconfig function to determine the characteristics of the 


video mode. This information includes such things as the number of x and 
y pixels in each dimension, and the number of colors allowed. 
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m 6 Restore the initial configuration 

Restore the system to its initial video mode by calling the function — set- 

videomode with the _DEFAULTMODE manifest constant. Failure to 
do this may cause the machine to “lock up” when another program is run. 


m@ Example: Skeleton graphics program 


#include <stdio.h> 


#include <graph.h> /* graphics include file */ 

int set_mode (void); /* prototype */ 

struct videoconfig vc; /* configuration data +*/ 

char error_message [] = "This video mode is not supported"; 
main () 


/* program requires 640 x 200 resolution */ 


if (!set_mode()){ /* if set_mode fails «/ 
printf ("%s\n", error_message) ; /* print message */ 
exit (0); /* and exit */ 


_getvideoconfig (&vc); /* video configuration data in vc */ 
/* do graphics operations here +*/ 


/* restore video mode +«/ 
_setvideomode (_DEFAULTMODE) ; 


/* function to set mode; 
assume program requires 640 x 200 resolution */ 
int set_mode() 


if (_setvideomode (_HRES16COLOR) ) /* VGA or EGA «/ 
return (_HRES16COLOR) ; 

if (_setvideomode (_HRESBW) ) /* VGA, EGA or CGA «/ 
return (_HRESBW) ; 

else 
return (0); 


} 


The program above shows an outline of a graphics program. 


81 


Microsoft QuickC Compiler Programmer’s Guide 


4.2 Setting the Video Mode 


All graphics programs operate in a graphics screen mode, which deter- 
mines the screen size (in pixels) and the number of colors allowed. The 
mode set by the program must be compatible with the hardware con- 
figuration. 


m Available modes 
The constants listed below are used to set the video mode. The dimensions 


are given in terms of pixels for graphics mode and in terms of rows and 
columns for text modes. 


Constant Video Mode Mode Type 
—~DEFAULTMODE Restores screen Both 

to original mode 
_~ TEXTBW40 40 x 25 text, 16 gray Text 
~ TEXTC40 40 x 25 text, 16/8 color Text 
~_ TEXTBWS80 80 x 25 text, 16 gray Text 
_~ TEXTC80 - 80x 25 text, 16/8 color Text 
—~MRES4COLOR 320 x 200 pixels, 4 color Graphics 
—~MRESNOCOLOR — 320 x 200 pixels, 4 gray Graphics 
—~ HRESBW 640 x 200 pixels, BW Graphics 
_~ TEXTMONO 80 x 25 text, BW Text 
~MRES16COLOR 320 x 200 pixels, 16 color Graphics 
~ HRES16COLOR 640 x 200 pixels, 16 color Graphics 
~ERESNOCOLOR 640 x 350 pixels, BW Graphics - 
~ ERESCOLOR 640 x 350 pixels, 4/16 color Graphics 
—~ VRES2COLOR 640 x 480 pixels, 2 color Graphics 
— VRES16COLOR 640 x 480 pixels, 16 color Graphics 


—~MRES256COLOR — 320 x 200 pixels, 256 color Graphics 


m Selecting the video mode 


Select a video mode with the required resolution for the project at hand. 
You will need to make trade-offs between increased resolution versus 
increased availability of colors. Call the _setvideomode function with 
one of the constants listed above to set the video mode. 


A return value of O indicates that the hardware does not support the 


selected mode. Take appropriate exit action if the hardware configuration 
does not support the required graphics mode. 
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After the video mode has been set, call the _ getvideoconfig function to 
determine the parameters of the mode selected (such as the dimensions of 
the screen). Put the video-configuration information into the video- 
configuration structure for use by other graphics functions. Use the video- 
configuration structure rather than absolute numbers to specify video 
screen characteristics. This ensures portability to other screen configu- 


rations (CGA, EGA, or VGA). 


m Resetting the video mode 


Always reset the video mode to the default mode that was present on 
entry into the program by calling _ setvideomode with the 
~DEFAULTMODE parameter. Failure to restore the video environment 
after a graphics program may cause the machine to “lock up” when 
another program is run. 


= Example: Setting the video mode 


#include <stdio.h> 

#include <graph.h> 

int set_mode (void); 

struct videoconfig vc; 

ay ee (] = "This video mode is not supported"; 
main 


if (!set_mode()) 
printf ("%s\n", error_message) ; 
exit (0); 


_getvideoconfig (&vc); /* put configuration data into ve +/ 
/* the body of the program goes here *+/ 
_setvideomode (_DEFAULTMODE); /* restore video mode */ 
int set_mode () 
/* assume that the program requires.640 x 200 resolution */ 
if (_setvideomode (_HRES16COLOR) ) 
return (_HRES16COLOR) ; 
if (_setvideomode (_HRESBW) ) 
return (_HRESBW) ; 


else 
return (0); 
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4.3 Getting the Video Configuration 


All graphics configuration information is contained in a structure of type 
videoconfig. The template for this structure is defined in graph.h. Once 
the video mode has been set, the video-configuration information must be 
determined. 


m The videoconfig structure varjable 
Declare a variable to be of type videoconfig to receive the video configu- 
ration information. This structure variable will be used in the call to 


~ getvideoconfig in the following format: 


struct videoconfig vc; /* structure variable declaration «/ 


_getvideoconfig (&vc); /7* structure variable use «/ 


m™ Contents of the videoconfig structure 


The videoconfig structure is defined in the iGrapnics header file graph.h, 
and it contains the following items: 


struct videoconfig { 


short numxpixels; /* number of pixels on x axis */ 

short numypixels; /* number of pixels on y axis +/ 

short numtextcols; /* number of text columns available +/ 
short numtextrows; 7* number of text rows available */ 
short numcolors; 7* number of actual colors */ 


short bitsperpixel;: /* number of bits per pixel +/ 
short numvideopages; /* number of available video pages */ 


r 
m™ Using the video configuration information 
Use the video configuration information to determine the dimensions of 


the screen. In any graphics mode, the center of the screen is given by the 
following coordinates: 


xcenter = vc.numxpixels/2 - 1; /* x coordinate of center */ 
ycenter = vc.numypixels/2 - 1; /* y coordinate of center +«/ 


The variable vc. vcnumxpixels is the number of x pixels and 
vc.vcnumypixels is the number of y pixels in the current video mode. 
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m Example: Accessing the video-configuration structure 


#include <stdio.h> 
#include <ctype.h> 
#include <graph.h> 


struct videoconfig vc; /* variable vc of type videoconfig */ 


/*x define an array of video modes and mode names 
since the numbers are not continuous */ 


int modes[12] = {_TEXTBW40, _TEXTC40, _TEXTBW80, _TEXTC8O, 
_MRES4COLOR, _MRESNOCOLOR, _HRESBW, _TEXTMONO, 
_MRES16COLOR, _HRES16COLOR, _ERESNOCOLOR, _ERESCOLOR}; 


char *modenames[] = {''TEXTBW40", "TEXTC40", "TEXTBW80", 
"TEXTC80", "MRES4COLOR", "MRESNOCOLOR", 
"HRESBW", "“TEXTMONO", '"MRES16COLOR", 
“"HRES16COLOR", "“ERESNOCOLOR", '"ERESCOLOR"}; 
main () 


int i: 

/* test all video modes «/ 

for (i=O; i<= 11; i++) { 
_setvideomode (modes[i]); 
_getvideoconfig (&vc); 
printf ("\n video mode:\t%s\n",modenames [i]); 
printf (" x pixels:\t%d\n",vc.numxpixels) ; 
printf y pixels:\t%d\n", vc.numypixels) : 
printf (" text columns:\t%d\n",vc.numtextcols) ; 
printf (" text rows:\t%d\n",vc.numtextrows) ; 
prince # of colors:\t%d\n",vc.numcolors) ; 
printf (" bits/pixel:\t%d\n",vc.bitsperpixel) ; 
printf (" video pages:\t%d\n",vc.numvideopages) ; 
printf Hit return for next video mode"); 
_setcolor (2); 
_rectangle (_GBORDER,0,0,vc.numxpixels-5, 
ve.numypixels-S) ; 
getchar (); 
_clearscreen (_GCLEARSCREEN) ; 


- 
= 


} 
_setvideomode (_DEFAULTMODE) ; 
} 


The program above calls each possible video mode and prints the video- 
configuration information about it. The program also draws a rectangle 
around the edges of the screen. 
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4.4 Using the Color Text Modes 


Two color text modes, . TEXTC40 and _ TEXTC80, can be used with 
the CGA, EGA, and VGA displays. These modes display any of 16 fore- 
ground colors with any one of 8 background colors. 


m= # Basics of text color selection 


In a text mode, each displayed character requires two bytes of video 
memory. The first byte contains the ASCII code representing the charac- 
ter, and the second byte contains the display attribute. In the CGA color 
text modes, the attribute byte determines the color and whether it will 
blink. Sixteen colors are available: the CGA pixel values, and the default 
EGA and VGA pixel values. Since the EGA and VGA palette can be 
remapped, these values can be made to correspond to any set of 16 colors 
with the appropriate palette mapping. (See Sections 4.6 and 4.7 for infor- 
mation on remapping EGA and VGA pixel values, respectively.) 


m Using text colors 


Use the _ gettextcolor function to find the pixel value of the current text 
color. 


The pixel values in the range 0-15 are interpreted as normal color. Pixel 
values in the range 16-31 are the same colors as those in the range 0-15, 
but with blinking text. 


Set the color in text modes with the _settextcolor function. This func- 
tion uses a single argument which specifies the pixel value to be used for 
text operations. A pixel value of 0 produces no visible output, since it 
always represents the current background color. The text color does not 
affect normal C output. The — outtext function should be used to output 
colored text. 


The pixel values for color text modes are defined below: 


No. Color No. Color No. Color No. Color 

0 Black 4 Red 8 Dark gray 12 Light red 

1 Blue 5 Magenta 9 Light blue 13 Lt. magenta 
2 Green 6 Brown 10 Light green 14 Yellow 

3 Cyan 7 White 11 Light cyan 15 Bright white 
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m @6Example: Viewing text colors 


#include <stdio.h> 
#include <graph.h> 
char buffer [255]; 
main () . 
* 
int i,j; 
long int delay; 
_setvideomode (_TEXTC8O) ; 
for (j=O; j<= 7; jtt) { 
_setbkcolor (j); /* background colors */ 
_settextposition (1,1); 
printf ("bkcolor: %d\n", j); 
for (i=O; i<= 15; itt) { 
_settextcolor (i); /* text colors +/ 
_settextposition (5+1i,1); 
sprint’ (buffer, “Color: -Yd\n" -1)3 
_outtext (buffer); 


/* pause */ 
for (delay = 0; delay <= 200000; delay+t); 


¢ 


+ 
_clearscreen (_GCLEARSCREEN) ; 
_setvideomode (_DEFAULTMODE) ; 


} 


The program above cycles through all background color and text color 
combinations. 
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4.5 Using the CGA Color Graphics Modes 


The CGA color graphics modes (that is, _-MRES4COLOR and 
~MRESNOCOLOR) display four colors (or shades of gray) selected 
from one of several predefined palettes of colors. They display these fore- 
ground colors against a background color selected from a set of 16 possible 
colors. 


=m CGA color graphics 


In a graphics mode, a pixel can be represented as a one-, two-, or four-bit 
value depending upon the mode selected. This representation is known as 
the “pixel value.” In addition to the pixel value there is an ordinal color 
representation. Each color that can be displayed in a particular video 
mode is represented by a unique ordinal value. The mapping of pixel 
values onto the actual display colors produces a “palette” of colors that 
can be displayed. 


The CGA color graphics modes provide four palettes of four colors. A 
palette defines a subset of all possible colors, and it consists of the back- 
ground color (pixel value 0) and three set foreground colors. A palette 
defines the characteristics of the entire display. 


The background color may be any one of the 16 available colors. With the 
CGA hardware, the palette of foreground colors is predefined and cannot 
be changed. The palette number is an integer value that selects one of the 
predefined palettes. 


m= §@6Using palettes 


Four palettes are available in the .MRES4COLOR video mode. Use the 
—selectpalette function to select one of these palettes. The table below 
shows the correspondence between the pixel values and colors for each 
palette. The background color may be set to any of the 16 possible colors. 


Pixel Value 


Palette 
Number 
0 Green Red Brown 
1 Cyan Magenta Light gray 
2 Light green Light red Yellow 
3 Light cyan Light magenta White 
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Use the _MRESNOCOLOR video mode with black-and-white displays 
to produce palettes consisting of various shades of gray. The 
~MRESNOCOLOR mode will also produce colors when used with a 
color display. However, only two palettes are available with a color 
display. Use the —~ selectpalette function to select one of these predefined 
palettes. The table below shows the correspondence between the pixel 
values and colors for each palette. 


Pixel Value 
Palette 


Number 
0 Blue Red Light gray 
1 Light blue Light red White 


You may use the —_selectpalette function only in conjunction with the 
~MRES4COLOR and -MRESNOCOLOR video modes. 


m Example: Viewing palette colors 


#include <stdio.h> 
#include <graph.h> 
long bkcolor [8] = {_BLACK, _BLUE, _GREEN, _CYAN, 
_RED, MAGENTA, _BROWN, _WHITE}; 
char *bkcolor_name [] = {"_BLACK", "_BLUE", "_GREEN", 
"_CYAN", "_RED", "_MAGENTA", "_BROWN", "_WHITE"}; 
main () 


int i, j, k, delay; 
_Setvideomode (_MRES4COLOR); /* uses CGA color mode */ 
for (k=O; k <= 7; k++) 
_setbkcolor (bkcolor [k]); 
for (i1=O; i<x= 3; itt) { 
_selectpalette (i); 
for (j=O;: j<=3: jtt) f 
_settextposition (1,1); 
_setcolor (j) 
printf ("background color? {8s\n", bkcolor _name[k]); 
printf ("palette: %d\ncolor: %d\n",i,j); 
_rectangle (_GFILLINTERIOR,160,100, 320, 200) ; 
for (delay=0; delay <= 20000; delaytt) 


} 
} 


_setvideomode (_DEFAULTMODE) ;: 


This program sets the video mode to _MRES4COLOR and then cycles 
through background colors and palette combinations. 
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4.6 Using the EGA Color Graphics Modes 


Use the .MRESI6COLOR, —HRES16COLOR, or _ERESCOLOR 
video modes to display the best color graphics with an EGA adapter. The 
CGA modes will also display on the EGA but with the lower CGA resolu- 
tion and decreased color options. 


m™ =68©EGA color graphics modes 


In a graphics mode, a pixel can be represented as a one-, two-, or four-bit 
value depending upon the mode selected. This representation is known as 
the “pixel value.” In addition to the pixel value there is an ordinal color 
representation. Each color that can be displayed in a particular video 
mode is represented by a unique ordinal value. The mapping of pixel 
values onto the actual display colors produces a “palette” of colors that 
can be displayed. 


A palette of colors is available whenever one of the EGA graphics modes is 
used. The EGA palettes may be remapped and redefined by the program. 
The default palette for the EGA modes is the same as the palette for the 
color text modes. 


m Remapping individual colors 


Use the _ remappalette function to remap one pixel value to a specified 
color, which must be a color supported by the current video mode. For 
example, the function below remaps the pixel value 1 to the value __RED. 
After this statement, whatever was displayed as blue will now appear as 
red: 


_remappalette (1, _RED); /* reassign blue to red +/ 


m= Remapping a set of colors 


Use the _ remapallpalette function to remap all of the pixel values simul- 
taneously. The function’s argument points to an array of color numbers 
reflecting the remapping. The first color number in the list will become the 
new color associated with the pixel value of 0. 


The number in a function call to set the color (such as — setcolor) is an 
index into the palette of colors available. In the default text palette, an 
index of 1 refers to blue. When a palette is remapped, the order of colors 
in the palette is changed. As a result, the color produced by a given pixel 
value also changes. The number of colors mapped depends on the number 
of colors supported by the current video mode. 
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The —remappalette and _ remapallpalette functions work in all modes 
but only with the EGA or VGA hardware. The _remappalette and 
—remapallpalette functions fail and return a value of —1 when you 
attempt to remap a palette without the EGA or VGA hardware. 


= Sample: Remapping color palettes 


#include <stdio.h> 
#include <graph.h> 


main () 
_setvideomode (_ERESCOLOR) ; 


_settextposition (1,1); /* normal palette +*/ 
printf ("Normal palette"); 


—setcolor (4); /* red in default palette +«/ 
_rectangle (_GFILLINTERIOR, 50,50, 200, 200); 

getchar (); /* wait for Enter key +*/ 
_remappalette (4, _BLUE); /* make red into blue */ 


_settextposition (1,1); 
printf ("Remapped palette"); 


_setcolor (4); /* blue */ 

rectangle (_GFILLINTERIOR, 50,50, 200,200); 
getchar (); /* wait for Enter key +«/ 
_remappalette (4, _RED); /* restore */ 


_settextposition (1,1); 
printf ("Restored palette"); 


_setcolor (4); /* red */ 
_rectangle (_GFILLINTERIOR, 50,50, 200, 200) ; 
getchar (); /* wait for Enter key +*/ 


_Cclearscreen (_GCLEARSCREEN) ; 
_setvideomode (_DEFAULTMODE) ; 


This program draws a rectangle with a red interior. In the default EGA 
palette, the pixel value 4 maps to the color red. This pixel value is 
remapped to BLUE in this program and the rectangle is redrawn. 
Finally, the pixel value is remapped back to the original color. 
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4.7 Using the VGA Color Graphics Modes 


Use the video modes _. VRES2COLOR, —~ VRESI6COLOR, and 

~ MRES256COLOR with the VGA display. EGA and CGA modes can 
also be used with the VGA hardware, but with either lower resolution or 
decreased color choices. 


=# VGA color graphics modes 


In a graphics mode, a pixel can be represented as a one-, two-, or four-bit 
value depending upon the mode selected. This representation is known as 
the “pixel value.” In addition to the pixel value there is an ordinal color 
representation. Each color that can be displayed in a particular video 
mode is represented by a unique ordinal value. The mapping of pixel 
values onto the actual display colors produces a “palette” of colors that 
can be displayed. 


The VGA color graphics modes operate with a range of 262,144 (equiva- 
lent to 256K) colors. The _WRES2COLOR graphics mode displays two 
colors, the VRESI6COLOR graphics mode displays 16 colors, and the 
~MRES256COLOR graphics mode displays 256 colors from the avail- 
able VGA colors. 


The large number of possible colors in the VGA is made possible by the 
use of three bytes of information to represent the intensities of red, green, 
and blue for each screen pixel. In each byte, the two high-order bits must 
be 0. The remaining six bits represent the intensity of blue, green, and red 
(reading from high-order byte to low-order byte). Three colors, each with 
six bits of intensity, yield 64°3 or 262,144 colors. 


For example, equal values of red, green, and blue are used to make low- 
intensity white so that the three-byte color number would be 


blue green red 
00011111 00011111 00011111 
DG. ese SST ea es > low order 


Because of the splitting of color numbers between bytes, the color numbers 
are not continuous (as is the case with CGA or EGA modes). 


The 16 colors of the default palette for the _VRESI6COLOR mode and 


the first 16 colors of the default palette in the _MRES256COLOR mode 
are the same as that for the color text modes. 
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= Remapping individual colors 


Use the _remappalette function to remap one pixel value to a specified 
color number. The function below remaps the pixel value 1 to the color 
value given by the manifest constant _RED haley represents red). After 
this statement is executed, whatever was displayed as blue will now appear 
as red. 


_remappalette (1, _RED); /* reassign blue to VGA red +«/ 


m Remapping a set of colors 


Use the _remapallpalette function to remap all of the available pixel 
values simultaneously. The function’s argument points to an array of color 
numbers reflecting the remapping. The first color number in the list will 
become the new color associated with the pixel value of 0. 


The number in a function call to set the color (such as _setcolor) is an 
index into the palette of colors available. In the default text palette, an 
index of 1 refers to blue. When a palette is remapped, the order of colors 
in the palette is changed. As a result, the color produced by a given pixel 
value also changes. The number of colors mapped depends on the number 
of colors supported by the current video mode. 


The _remappalette and _remapallpalette functions work in all modes 
but only with the EGA or VGA hardware. The _remappalette and 
—remapallpalette functions fail and return a value of —1 when you 
attempt to remap a palette without the EGA or VGA hardware. 


Manifest constants for the default color numbers are supplied so that the 
remapping of VGA colors is compatible with EGA practice. The names of 
these constants are self-explanatory. For example, the color numbers for 
black, red, and light yellow are represented by the manifest constants 
—~BLACK, — RED, and _LIGHTYELLOW. 


All of the VGA display modes operate with any VGA video monitor. 
Colors are displayed as shades of gray when the monochrome analog 
display is connected. 


m Example: Remapping VGA color palettes 


long colorsl [16] = {_BLACK, _BLUE, _GREEN, _RED, _RED, _MAGENTA, 


_BROWN, _WHITE, _GRAY, _LIGHTBLUE, _LIGHTGREEN, _LIGHTRED, 
_LIGHTRED, _LIGHTMAGENTA, _LIGHTYELLOW, _BRIGHTWHITE}; 


The array of color numbers above remaps the default VGA palette so that 
the cyan and light cyan colors are displayed as red and light red. 
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4.8 Understanding Coordinate Systems 


A “coordinate system” is used to identify a pixel location relative to a hor- 
izontal and vertical axis. In a graphics mode, each pixel on the screen can 
be located by means of a unique pair of coordinates. The graphics library 
of functions supports two coordinate systems: a physical system and a log- 
ical system. 


m= Physical coordinates 


The “physical-coordinate system” places the origin (or the coordinate pair 
0,0) at the upper-left corner of the screen. Increasing positive values of the 
x coordinate extend from left to right. Increasing positive values of the y 
coordinate extend from top to bottom. Thus, the bottom-right corner of 
the screen has an x coordinate equal to the number of x pixels available in 
the particular graphics video mode. Likewise, the bottom-right corner of 
the screen has an y coordinate equal to the number of y pixels available in 
the particular graphics video mode. 


The physical-coordinate system contains only positive values with the x 
coordinate ranging from 0 (upper-left corner) to the number of x pixels 
(right margin) and the y coordinate ranging from 0 (upper-left corner) to 
the number of y pixels (bottom margin) 


The physical-coordinate system is dependent on the hardware and display 
configuration, and cannot be changed. 


m™ Logical coordinates 


A “logical-coordinate system” is created by moving the origin to a more 
“logical” position relative to the absolute physical coordinates. It is de- 
fined with the _setlogorg function, which sets a new logical origin. Ini- 
tially, the default logical-coordinate system is identical to the physical- 
coordinate system. 


After the origin is moved, the x and y coordinates maintain their orienta- 
tion. As x increases, the pixel position moves from left to right on the 
screen. As y increases, the pixel position moves from top to bottom on the 
screen. 
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m Repositioning the origin 


The program segment below repositions the origin to the center of the 
screen: 


_getvideoconfig (&vc); 
_setlogorg (vc.numxpixels/2-1, vc.numypixels/2-1) ; 


The call to the function _ getvideoconfig returns the configuration infor- 
mation in the structure variable vc. The configuration structure contains 
the data on screen size. This is used (after an appropriate division) to re- 
position the origin to the center of the screen. 


m™ Resetting to physical coordinates 


Reset the logical origin to the physical origin (which is the upper-left pixel 
of the screen) with the function _setlogorg. An example of resetting the 
logical origin is shown below: 


_setlogorg(0,0); 


m™ Converting between coordinate systems 


Use the - getlogcoord function to translate the physical coordinates to 
logical coordinates. The logical coordinates are returned in an xycoord 
structure. Use the _ getphyscoord function to translate the logical coor- 
dinates of a specified pixel to physical coordinates. The physical coordi- 
nates are returned in an xycoord structure. The form of these two func- 
tions is shown below: 


— getlogcoord (z,y); 
_ getphyscoord (z,y); 


m= Example: Finding the screen centerpoint 


_getvideoconfig (&vc); /* get videoconfig information */ 
x = vce.numxpixels/2 - 1; /* determine x and y midpoints */ 
y = ve.numypixels/2 -1; 

—setlogorg (x, y); /* reposition origin */ 


This program segment finds the screen center point for any video mode 
and sets the logical origin there. 
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4.9 Plotting Points 


The simplest graphics functions operate at the single-pixel level. Any indi- 
vidual pixel can be accessed, examined, and set. 


™ Moving to a particular screen point 


Change the current graphics position with the  moveto function. This 
function moves the current position (where the next graphics operation 
takes place) to the specified logical coordinate. Its format is 


_moveto (10,10); /* 10 pixels from left & 10 pixels 
down from the logical origin */ 


m Setting and clearing pixels 


Use the — setpixel function to set a pixel located at the indicated logical 
coordinate to the current color. Its format is 


_setpixel (10,10); /* sets pixel at 10,10 to current color +/ 


Reset a pixel by setting it to the background color (which is always pixel 
value 0). Shown below is the sequence of commands necessary to clear the 
specified pixel: 


_setcolor (0); /* set color to background color +«/ 
_setpixel (x, y); /* effectively clear pixel +/ 


= Example: Setting pixels 


The hyppix.c program below draws a hypocycloid, a figure created by 
rolling one circle inside another. The math-function library math.h is 
included because of the calls to the cosine and sine functions. The video 
mode used is CGA compatible. The curve is drawn during a while loop, 
which can be terminated by a keystroke. For interesting patterns, make 
the circle ratio larger than the pen position and do not use purely integer 
values. A particularly interesting pattern arises if the circle ratio is 3.2 
and the pen position is 1.6. (More information on hypocycloids and other 
cycloids can be found in the “Mathematical Recreations” column of the 
May, 1987, issue of Byte magazine.) 
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/* hyppix.c -- hypocycloid plotter (pixel version ) +*/ 
#include <stdio.h> 

#include <graph.h> 

#include <math.h> 

#include <conio.h> 

struct videoconfig vc; 


char error_message [] = "This video mode is not supported"; 
main () 
if (_setvideomode (_MRES4COLOR) == 0) { 
printf ("%s\n", error_message) ; 
exit (0); 


_getvideoconfig (&vc); 

hypcycle(); /* call drawing function +/ 
_clearscreen (_GCLEARSCREEN) ; 

_setvideomode (_DEFAULTMODE);: /+* restore video mode +«/ 


Peeve 
{ 


float pi=3.14159; /* Geclare and initialize */ 
float a,h,b,r,x0O,yO,x,y, ang: 
Ane is 
xO = vc.numxpixels/2 -1; 
yO = vc.numypixels/2 -1; 
printf ("circle ratio (>=1): "); 
scanf ("%f", &r); 
printf ("\npen position (>1): "); 
scanf ("%f",&h); 
_Cclearscreen (_GCLEARSCREEN) ; 
_setcolor (1); 
—moveto (x0,0); /* draw axes */ 
_lineto (x0,vc.numypixels); 
_moveto (0,y0); 
_lineto (vc.numxpixels, yO) ; 
a = 0.5*r#ve.numypixels/(r+h-1); 
b = a/r; 
h = htb; 
_setcolor (2); 
ang = O; 
while (!kbhit()) { /* draw hypocycloid +/ 
for (i=1; i<= 20; i+t) €{ 
ang = ang + 2*pi/100; 
x = x0+ (a-b) «cos (ang) th*cos (angt (a-b) /b); 
y = yO- (a-b) *sin (ang) +h*sin (ang* (a-b) /b) ; 
_setpixel (x,y); 


} 
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4.10 Drawing Lines 


Use the — moveto and — lineto functions to draw lines between any two 
points. The line may be drawn with either a solid or patterned line style. 


m Moving to a specified location 


Use the — moveto function to move to the logical-coordinate position 
given by the pair of points specified in the function. The form of the 
—moveto statement is as follows: 


_moveto (25, 25); /* move to logical coordinate 25,25 +#/ 


m Drawing lines 


Use the — lineto function to draw a line from the present cursor position 
to the pair of endpoints specified in the function. Once the line has been 
drawn successfully, the current position is set to the coordinates specified 
in the — lineto function. The color used is the current color. After execut- 
ing the _moveto function above, the — lineto call below would draw a 
line from the point (25,25) to the point (100,100) and set the new current 
position to (100,100): 


_lineto (100,100); /* draw line from current position 

/* to 100,100 «/ 
m Drawing dashed or patterned lines 
The line-style mask controls the appearance of a line. The mask is a 16-bit 
template used for line drawing. Each bit in the mask represents a pixel in 
the line. If a bit’s value is 1, the corresponding pixel is set to the current 
color. If a pixel is 0, the pixel is set to the background color. The default 
mask is a solid line (OxFFFF). 


The — setlinestyle function affects the line used in the — lineto and — rec- 
tangle functions. 


The following is an example that changes the line style to a dashed line: 


_setlinestyle (OxAAAA); /* line style 1010101010101010 +«/ 


98 


Graphics Quick Start 


@ Example: Line drawing 


#include <stdio.h> 
#include <graph.h> 
#include <conio.h> 
struct videoconfig vc; 


char error_message [] = "This video mode is not supported"; 
main () 
if (_setvideomode (_MRES4COLOR) == 0) { 
printf ("%s\n", error_message) ; 
exit (0); 


_getvideoconfig (&vc); 

_setlinestyle (0x0001) ; 

_moveto (0,0); /* Qraw figure +*/ 
_lineto (0,150); 

_setlinestyle (OxObb0) ; 

_lineto (150,150); 

~setlinestyle (OxOff0); 

_lineto (150,0); 

_setlinestyle (Oxffff);: 

_lineto (0,0); 


getchar (); /* wait for return */ 
_clearscreen (_GCLEARSCREEN) ; /* clear entire screen */ 
_setvideomode (_DEFAULTMODE) ; /* restore video mode */ 


} 


The program above draws a rectangle with four different line styles for 
each side. 
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4.11 Describing Graphics Objects 


This section defines the fundamental concepts used to describe graphic 
objects. 


m= Bounding rectangle 


A bounding rectangle defines the space in which a circular figure is drawn. 
For a circular figure, the center of the bounding rectangle defines the 
center of the circular figure. In a sense, the bounding rectangle is the 
“square hole” into which the round object fits. A bounding rectangle is 
defined by the coordinates of the upper-left corner and the lower-right 
corner of the rectangle. The other two corners are implied in the call. 


m= Border 

The border of circular objects is drawn in the current color and with a 
solid line style. The border of a rectangular object is drawn in the current 
color and with any line style specified by the _setlinestyle function. If no 
value has been specified for the border, the default solid line style 

(OxF FFF) is used. 

m Fill flag 

Use the fill flag to specify whether a figure is to be filled using the current 
fill mask or if the figure is to remain empty. The _GFILLINTERIOR 
constant specifies the object should be filled, and _GBORDER specifies 
that only the border is to be drawn. 

m Start and end vector 

The arc or pie wedge starts at the point where the bounding rectangle 
intersects the start vector and ends where it intersects the end vector. 

m@ The aspect ratio 

The aspect ratio is the number of pixels in the vertical line divided by the 
number of pixels in the horizontal line. To draw squares (or circles), you 


have to scale their dimensions with the aspect ratio. 


- The aspect ratio depends on two factors: 


100 


Graphics Quick Start 


1. A horizontal row has more pixels than a vertical column of the 
exact same physical length in all screen resolutions, because of the 
spacing of pixels and their elongated horizontal shape. 


2. A video-display screen is wider than it is high, typically by a ratio 
of 4:3 


= Calculating the aspect ratio 
The formula for computing the aspect ratio for a given video mode is 
aspect ratio = (screenwidth/screenheight) * (ypizels/apizels) 


where screenwidth and screenheight refer to the physical dimensions of the 
display screen, and where zpizels and ypizels refer to the current screen 
resolution (as measured in pixels). 


m= Example: Drawing correctly proportioned figures 


#include <stdi.h> 

#include <math.h> 

#include <graph.h> 

struct videoconfig vc; 

char error_message [] = "This video mode is not supported"; 
main () 


float ar, x, y; 

if (_setvideomode (_MRES4COLOR == 0) { 
printf ("%s\n", error_message) ; 
exit (0); 


_getvideoconfig (&vc); 
/* screen dimensions 10 x 6.5 inches +/ 


ar = (float) (10 * vc.numypixels) / (6.5 * vc.numxpixels) ; 
y = 100*ar; 

x = 100: 

_setlogorg (vc.numxpixels/2 - 1, vc.numypixels/2 - 1); 


_setcolor (1); 

rectangle (_GFILLINTERIOR, -x, -y., x. y):; 

_setcolor (3); 

_ellipse (_GFILLINTERIOR, -x, -y, x, y); 

getchar (); 

_clearscreen (_GCLEARSCREEN) ; 

_setvideomode (_DEFAULTMODE); /* restore video mode +/ 


: 


This program uses the aspect ratio to correctly draw a square and a circle. 
The circular figure highlights the concept of a bounding rectangle. 
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4.12 Drawing Basic Shapes 


The basic shapes available with the C graphics library are the rectangle, 
the ellipse, the arc, and the pie-shaped wedge. 


m= Drawing rectangles 


Use the rectangle function to draw a rectangle. The arguments to the 
function specify the coordinates of the opposite corners. The other corners 
are implied. Use the fill-flag parameter to specify whether the rectangle is 
to be drawn with the border only or it is to be filled with the current color. 
The two commands below draw a rectangle in the upper-left quadrant of 
the screen. The opposite corners are at the coordinates (0,0) and (25,25). 


_rectangle (_GBORDER,O,0, 25,25); /* Graw border only */ 
_rectangle (_GFILLINTERIOR, 25,25,0,0); /x* fill interior */ 


= Drawing circles and ellipses 


Use the _ ellipse function to draw an ellipse. The parameters to the func- 
tion specify the opposite corners of a bounding rectangle. The center of 
the ellipse is the center of the bounding rectangle. If the bounding rectan- 
gle is a square, the ellipse is a circle. The command below draws two 
ellipses in the upper left quadrant of the screen: 


_ellipse (_GBORDER,0O,0,25,25); /* QGraw border only +*/ 
_ellipse (_GFILLINTERIOR, 25,25,0,0); /* fill interior */ 


If the concept of a bounding rectangle is a little confusing, you can call the 
ellipse function using only the center point (x,y) and the radius (r), as 
shown below: 


_ellipse (_GBORDER, x-r, y-r, xt+r, ytr); /* draw border only +/ 


m Drawing arcs and pies 


An arc is a segment of an ellipse; in other words, a short, curved line. A 

pie 1s a pie-shaped wedge consisting of an elliptical arc whose center and 
two endpoints are joined by lines. The pie-shaped area is filled with the 

current color. 


An arc or pie is drawn by specifying the opposite corners of a bounding 
rectangle and by specifying the endpoints of the vectors that determine 
the endpoints of the pie or arc. The center of an arc or pie is the center of 
the bounding rectangle. The arc or pie starts at the point where the vector 
defined by the center of the bounding rectangle and the third pair of 
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points intersects the bounding rectangle. The arc or wedge ends at the 
point where the vector defined by the last pair of points and the center of 
the bounding rectangle intersects the bounding rectangle. The arc or pie is 
drawn using the current color, moving in a counterclockwise direction. An 
arc is not a closed figure; therefore, it is not filled. The pie-shaped area, 
however, is filled with the current color. The examples below show the use 
of these calls: 


/* bounding rectangle determined by coordinates: (0,0) and (50,50) 
beginning vector (center of bounding rectangle) & (0,100) 
ending vector (center of bounding rectangle) & (100,100) «/ 

arc (0, O, 50, SO, O, 100, 100, 100); 

_pie (_GFILLINTERIOR, O, O, 50, 50, O, 100, 100, 100); 


= =€=Example: Figure drawing 


#include <stdio.h> 
#include <graph.h> 
#include <math.h> 
struct videoconfig vc; 


char error_message [] = "This video mode is not supported": 
main () 

int x = 50; 

int y = 40; 


if (_setvideomode (_MRES4COLOR) == 0) { 
printf ("%s\n", error Smessage)< 
exit (0); 


_getvideoconfig (&vc); 
~setlogorg (vc.numxpixels/2 - 1, vc.numypixels/2 - 1); 
_setcolor (1); 
~setlogorg (vc.numxpixels/2 - 1, vc.numypixels/2 - 1); 
_setlinestyle (0x5555); 

_rectangle (_GBORDER, -x, -y, x. y):; 

_setcolor (2); 

ellipse (_ GFILLINTERIOR, Sy EV Xe 

_setcolor (3); 

“pie (_GFILLINTERIOR,-x, -y, x, y, -x-10, y+10, x+10, y-10); 
getchar (); 
_clearscreen (_GCLEARSCREEN) ; 
~Ssetvideomode (_DEFAULTMODE); /* restore video mode */ 
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4.13 Filling Figures with Patterns 


Use the — floodfill function to fill any enclosed figure with a pattern of pix- 
els. An enclosed figure is a figure with no gaps in the line defining its 
border. 


m Filling shapes with patterns 


Use the — floodfill function to fill any enclosed figure with a pattern speci- 
fied by the fillmask parameter. The fill mask is an 8-by-8-bit template 
array with each bit representing a pixel in the overall template pattern. If 
the bit is 0, the pixel is left alone. If a bit is set to 1, the pixel is assigned 
the current color value. The fill-mask pattern is repeated over the entire 
area to be filled. The default fill mask is for a solid fill pattern. 


The fill mask operates in a transparent, overlay mode. If a bit in the mask 
is O, the pixel on the screen is left alone. A 1 in the mask causes the pixel 
to be set to the current color. Differently colored fill patterns can be cre- 
ated by setting the color between calls to the — floodfill function. 


A nonsolid border (line style not equal to OxFFFF) can lead to unpredict- 
able filling when used with — floodfill and to possible overflow of the 
graphics area. 

Use the — getfillmask function to return the current fill mask. Use the 
_setfillmask to set the current fill mask to a specified value. Shown below 
is the format of the fill-mask functions: 


_ getfillmask (fillmash); 
_ setfillmask (fillmask); 


Use a NULL fill mask to reset the fill mask to a solid fill pattern as shown 
below: 


_setfillmask (NULL); /* reset fill mask to solid fill */ 


m Creating a fill mask 


The fill mask is an 8-by-8-bit array that is generally defined in terms of a 
character array. Create a fill mask as shown below: 


1. Draw the pattern for a tile in a grid with eight columns and eight 
rows. Place a one (1) in any box to represent an “on” pixel. 


2. Convert the 8-bit binary numbers in each row to decimal integers. 
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3. Create an array of these eight digits as shown below: 


7x fill mask for X pattern 


binary decimal 
representation equivalent 
10000001 129 
01000010 66 
00100100 36 
00011000 24 
00011000 24 
00100100 36 
01000010 66 
10000001 129 */ 


char fill_mask [] = {129, 66, 36, 24, 24, 36, 66, 129}; 


4. Draw a figure and paint its interior, using the newly created fill 
mask. 


_setfillmask (fill_mask) ; 
_rectangle (_GFILLINTERIOR, 50,50, 25,100); 


# Example: Filling regions with patterns 


#include <stdio.h> 

#include souerrel: 

char maskl [] {0,66, 36, 24, 24, 36, 66,0}; /* 2 fill patterns +/ 
char mask2 [] = {0,24,0,102,102,0, 24,0}; 


char error_message [] = "This video mode is not supported"; 
main () 
if (_setvideomode (_MRES4COLOR) == 0) { 
printf ("%s\n", error_message) ;: 
exit (0); 


_setfillmask (mask1) ; 
_setcolor (1); /* use multiple colors +/ 
_rectangle (_GBORDER,0O,0,150,150) ; 
_setcolor (2); 
_floodfill (100,100,1); /* stop at border of color 1 +/ 
_setcolor (3); 
_setfillmask (mask2) ; 
wtloodfill, (100,100, 1)+ 
getchar (); /* Wait for carriage return */ 
_clearscreen (_GCLEARSCREEN) ; 
_setvideomode (_DEFAULTMODE); /* restore video mode +*/ 
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4.14 Drawing and Storing Figures 


Complex figures can be drawn and stored in memory for later use in ani- 
mations. The — getimage function stores an image in memory, and the 
_ putimage function draws a stored image on the screen. 


m Saving images to memory 


The dimensions of the screen image saved are determined by a bounding 
rectangle. Use the _getimage function, as in the example below, to copy 
the entire area defined by the bounding rectangle to a buffer in memory: 


_getimage (0, O, 10, 10, buffer): 


The bounding rectangle is in the upper-left corner of the screen bounded 
by the coordinates (0,0) and (10,10). The variable buffer is a pointer to 
the storage buffer for the screen image. 


m= Determining storage requirements for _ getimage 


The buffer. must be large enough to hold the image. Use the function 

_ getimagesize to determine the size needed to store the image before 
attempting to store the image. The example at the end of this section also 
shows how the malloc function is used to allocate the buffer storage 
required. 


m= Displaying images from memory 


Use the _ putimage function to copy the rectangular image stored in the 
buffer back to the screen, with its upper-left corner at the specified point. 
The function call below takes the image from the buffer in memory and 
copies it to the position on the screen with the upper left-corner coordi- 
nate of (50,50). The final parameter is the “action-verb” argument which 
determines how the memory image interacts with the current screen 
image. 


_putimage (50,50,buffer,_GPSET) ; 
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m= The _ putimage action-verb argument 


The action-verb argument controls how the stored image interacts with 
what is already on the screen. The action-verb manifest constants cause 
the following display operations: 


Constant Action 

—~GPSET Direct transfer 

~ GPRESET Direct transfer, color inverted 

—~GAND Logical AND of transfer and screen image 

—_GOR Superimposition of an image onto an existing 
image 

-~ GXOR Screen inversion where a point exists in buffer 


m Example: Drawing and storing a figure 


draw_and_store_figure() 


_setbkcolor (0); 

_setcolor (1); 

rectangle (_GBORDER,0,0,10,10); 

_setcolor (2); 

rectangle (_GFILLINTERIOR,1,1,9,9); 

_setcolor (3); 

_moveto (1,1); 

_lineto (9,9); 

_moveto (1,9); 

_lineto (9,1): 

buffer=(char far *)malloc((unsigned int) 
_imagesize(0,0,10,10)); 

_getimage (0,0,10,10, buffer); 


} 


This function draws a figure, determines the size required to store the 
image in memory, and then places the figure into a memory buffer for later 
use In an animation application. (This function will reappear in Section 
4.15, “Using Animation,” in a complete C animation program.) 
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4.15 Using Animation 


Simple animation can be done by drawing figures, erasing them, and then 
moving to a new location and redrawing them. For faster, more effective 
animation of complex figures, use the _ getimage and _ putimage func- 
tions. 


m Creating animation 


Create an image using output from other graphics functions, and then 
take a “snapshot” of that image with _ getimage, copying it to memory. 
With — putimage, you then reproduce anywhere on the screen the image 
stored with — getimage. 


The two action verbs best suited for animation are _GXOR and 
~GPSET. Animation done using _GPSET is faster, but erases the 
screen background. In contrast, _GXOR is slower, but preserves the 
screen background. 


m Using ~GXOR in animation 
Animation with _ GXOR is done with the following four steps: 


Put the object on the screen with _GXOR. 
Calculate the new position of the object. 


Put the object on the screen a second time at the old location, 
using _ GXOR again—this time to remove the old image. 


4. Go tostep 1, but this time put the object at the new location. 


Movement done with these four steps leaves the background unchanged 
after step 3. Flicker can be cut down by minimizing the time between steps 
4 and 1, and by making sure that there is enough time delay between steps 
1 and 3. If more than.one object is being animated, every object should be 
processed at once, one step at a time. 


m Using ~GPSET in animation 


If it is not important to preserve the background, animation can be per- 
formed using the _GPSET option. If the border of the bounding rectan- 
gle around the image is as large as or larger than the maximum distance 
the object will move, then each time the image is put in a new location, 
the border will erase all traces of the image in the old location. 
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= Example: Animation using memory storage of images 


previous includes from hyppix.c 
#include <malloc.h> /* needed for buffer use +«/ 


declarations from hyppix.c 


char far *buffer; /* used with _getimage & _putimage */ 
main () 


; body of program from hyppix.c 


Reavoiet 
{ ; 


declarations and initialization from hyppix.c 


draw_and_store_figure(); /* place figure in buffer */ 
_clearscreen (_GCLEARSCREEN) ; 


drawing of axes as in hyppix.c 


js plot points and put image from buffer to screen */ 
while (!kbhit()) { 

for (1=1: a<— 20; .-i++) 4 

ang = ang + 2*pi/100; 

x xO+ (a-b) *cos (ang) th*cos (ang (a-b) /b) ; 
y = yO- (a-b) *sin (ang) th*sin (ang (a-b) /b); 
_putimage (x,y,buffer,GXOR) ;: 
for (j=l: j<=6000; j+t) 


_putimage (x,y, buffer ,GXOR) ; 


} 
a 
draw_and_store_ figure () 
: function contents from previous section 
} 


The hypocycloid program from Section 4.9 has been modified to draw the 
curve using the stored pattern and to draw this curve over a background 
on the screen. The draw_and_store_ figure function is from Section 


4.14, and it uses the _ getimage function to store a complex graphics 


figure in a buffer area. The skeleton of the program is shown above with 


notations of the changes. 


109 


THE QUICKC 
PROGRAMMING 
HK NVIRONMENT 


ParT2 


<> “Tae Quick 
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This part of the manual describes how you can 
use the QuickC programming environment to 
create, compile, debug, and run programs. This 
section shows you how to use the QuickC menu 
commands to 


e Customize the QuickC display by using the 
commands in the View menu (Chapter 5) 

e Create a new source file containing QuickC 
source code, or load an existing source file, 
using the commands in the File menu 
(Chapter 6) 

e Enter the source file using the editing com- 
mands, the Edit menu, and the Search 
menu (Chapter 7) 

e Compile, debug, and run the program using 
the Run menu (Chapter 8) 
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Controlling the Display: the View Menu 


Use the commands from the View menu to 


e Open windows 
e Display program output 


e Customize your screen’s appearance 


The View menu is shown in Figure 5.1. 


Include 


Options... 
Output Screen F4 


Errors 


Figure 5.1 The View Menu 


The commands on the View menu perform the following actions: 


Command Action 

Source... Displays the current program list. 

Include Displays a given include file. 

Options... Customizes the display by changing background 


and foreground colors, setting tab stops, and con- 
trolling the display of ‘scroll bars. 


Output Screen Shows you the output screen. The shortcut key for 
this command is F4. 


Errors Opens or closes the error window at the bottom of 
the QuickC screen. 


The following sections describe how to use the commands on the View 
menu. 


5.1 Viewing the Program List: 
the Source... Command 


Use the Source... command to look at any module in the current program 
list. This command is active only if you have loaded a program list with 
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the Set Program List... command in the File menu. (See Section 6.2.6, 
“Creating and Loading Program Lists: the Set Program List... Com- 
mand,” for information on using this command.) This command provides a 
fast way to move between modules without having to use the Open com- 
mand. Using Source... is easier than using Open... because 


e The Source... command lists only files that are part of the program 
list; the Open... command may list many more files. 


e The Source... command lists files in the program list that reside in 
other directories; the Open... command lists only files in the cur- 
rent directory. 


When you choose the Source... command, the dialog box shown in Figure 
5.2 appears: 


Name of the current program list 


View: C:\SRC\lexer.c 


lexer.c 
gettoken.c 


The list box shows all files in the current program list. 


Figure 5.2 The Source... Dialog Box 
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All modules in the list are displayed, regardless of the drive or directory 
where they reside. Use the DIRECTION keys to select the module you want 
to view. Then press ENTER to display the module. 


5.2 Viewing Include Files: 
the Include Command 


Use the Include command to display include files. You can display include 
files in one of two ways: 


1. Use the DIRECTION keys to move the cursor until it is resting on the 
same line as an # include directive; then choose the Include com- 
mand to display that include file. 


2. Choose the Include command and press ENTER. A dialog box 
appears. The default file specification in the File text box is «.h. 
Choose the include file from the list box and choose the OK com- 
mand button. 


After viewing an include file, press F2 to return to the file you were editing. 


5.3 Customizing the Display: 
the Options... Command 


The Options... command lets you change the appearance of the QuickC 
screen. With the Options... command you can change the foreground and 
background screen colors, alter the way program lines are displayed, re- 
move the scroll bars, or change the tab spacing. 


When you select Options... from the File menu, the dialog box shown in 
Figure 5.4 opens. 
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Display Attributes 


Foreground Background 


Normal Text [ ] Highlight 
CX] Highlight 
Current Statement { ] Blink 
CJ 


Underline 


CX] Highlight 
Breakpoint Lines red C J Blink 
C J Underline 


Display Options CX] Prompt before saving files 
CX] Scroll Bars 


Figure 5.3 The Options... Dialog Box 


The following options in the Display Attributes box determine the screen’s 
colors: 


Option Use 


Normal Text Specifies colors used to display program state- 
ments. The background color you choose sets 
the background color for the edit screen. 


Current Statement Specifies colors used to display the currently 
executing line. 


Breakpoint Lines Specifies colors used to display breakpoints (pro- 
gram lines where you temporarily stop program 
execution during debugging). 


The Normal Text option can be set so that program text is highlighted. 
The Current Statement and Breakpoint Lines options can be set so that 
they are highlighted, blinking, underlined, or any combination of the 
three. (Underlining is available only on systems with a Monochrome 
Display Adapter.) 


Choose colors for Normal Text, Current Statement, and Breakpoint Lines, 
using either of the following methods: 


e While the option is selected, type the first letter of the color you 
want. Note that the letter “B” represents both black and blue. 
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e While the option is selected, use the UP and DOWN keys to scroll 
through the color list until the name of the color you want appears 
in the box. 


Color choices are useful only on a color monitor. On a monochrome moni- 
tor, only Black and White are in the list of background colors. If you 
choose White instead of Black as the background color, the display 
changes to reverse video. 


The Display Options items control display of the following items: 
Option Use 


Scroll Bars Toggles (turns on or off) the display of scroll 
bars in the view window. The scroll bars are use- 
ful only if you have a mouse. If you are not 
using a mouse, turning the scroll bars off gives 
you more space in the window for text. 


Tab Stops Sets the number of columns between tab posi- 
tions. The default value is eight spaces. 


All the Display Options are on by default. 


The “Prompt before saving file” check box controls whether QuickC 
automatically saves changes to the file you are working on if you do some- 
thing that might result in a loss of changes (such as load or create a new 
file). If this check box is selected, QuickC displays a prompt asking if you 
want to save changes; you can choose the Yes command button to save 
changes or the No command button to discard them. If this check box is 
not selected, QuickC automatically saves changes without displaying a 
prompt. 


5.4 Viewing Program Output: 
the Output Screen Command 


The Output Screen command tells QuickC to display the program-output 
screen instead of the edit screen This command is typically used to look at 
output during program debugging. 

After you choose this command, press any key to return to the edit screen. 


The shortcut command for the Output Screen command is F4. 
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5.5 Opening or Closing the Error Window: 
the Errors Command 


If errors occur during compilation, QuickC opens an error window at the 
bottom of the screen to display these errors. The Errors command tells 
QuickC to close the error window if is currently open or to open the error 
window if it is currently closed. A check mark appears next to this com- 
mand on the menu when the error window is open. 


See Section 7.3.4, “Finding Program Errors: the Next Error and Previous 


Error Commands,” for more information about handling compilation 
errors. 
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Creating and Saving Programs 


This chapter explains how to create and save programs with the Microsoft 
QuickC Compiler. First, it shows how modules are combined to form pro- 
grams and describes the list of modules, known as the “program list,” that 
can be maintained for each program. Then it shows how to use commands 
from the File menu to create, save, and print QuickC source files. 


6.1 Programs and Modules: 
the Program List 


A QuickC program consists of one or more C source files known as 
“modules.” A program built from a single module is known as a “single- 
module program.” A program built from more than one module is known 
as a “multiple-module program.” 


You can maintain a list of the modules that make up a QuickC program in 
a file known as a “program list.” QuickC uses a program list to rebuild a 
program when any of its modules changes. This mechanism ensures that 
the program is always rebuilt using the most up-to-date versions of its 
modules. 


6.1.1 Single-Module Programs 


Single-module programs are the easiest to create. The usual process for 
creating a single-module program is: 


1. Choose the New command (Section 6.2.1) from the File menu to 
create a new C source file, or choose the Open... command (Section 
6.2.2) from the File menu to open an existing source file. 


2. Enter program text using the editing keys and commands described 
in Chapter 7. 


3. Compile, run, and debug the program using the commands 
described in Chapter 8. 


You are not required to create a program list for a single-module program. 
If you do not create a program list, the program is created in memory, and 
no executable file is created on disk. 


If the program calls standard C library routines, it can find definitions of 
most of these routines built into the QuickC programming environment. 
Table 6.1 lists the library routines that are built into QuickC, which are 
known collectively as the QuickC “core library.” 
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Table 6.1 

C Library Routines Defined in QC.EXE! 

abort _fmalloc Itoa rmdir strncat 
access _fmsize malloc rmtmp - strncemp 
atexit fopen memavl sbrk strncpy 
atof fprintf memecpy scanf strnset 
atoi fputec memchr segread strpbrk 
atol fputs memcmp setbuf strrcehr 
bdos fread memepy setjmp strrev 
brk free _memmax setmode strset 
calloc _freect memmove setvbuf strspn 
chdir fscanf memset signal strstr 
chmod fseek mkdir sopen strtok 
clearerr fstat movedata spawnl strupr 
close ftell _msize spawnle system 
cputs © fwrite _nfree spawnlp tell 
creat getch _nheapchk spawnlpe time 
dosexterr getche _nheapset spawnv tmpfile 
eof getcwd _nheapwalk spawnvpe“~ tmpnam 
exit _getdate _nmalloc sprintf tolower 
exit getenv _nmsize sscanf toupper 
_expand gets onexit stackavail tzset 
fclose gettime open streat ultoa 
flush int86 printf strchr ungetc 
_ffree int86x putch strcmp unlink 
fgets intdosx _ puts strempi vfprintf 
_fheapchk isatty raise strcpy vprintf 
_fheapset itoa read strespn vsprintf 
_fheapwalk kbhit realloc strdup write 
filelength longjmp remove stricmp 

flushall lseek rewind strlwr 


! The halloc, hfree, and exec family functions are defined within QC.EXE, but they cannot 
be called by programs running within the QuickC programming environment. 


2 These functions cannot be called with the P_OVERLAY mode flag by programs running 
within the QuickC programming environment. 


The QuickC compiler generates an error if any functions in your program 
have the same names as functions defined in the QuickC core library. 


If a program calls standard C library functions that are not listed in Table 
6.1, you must do one of the following to make sure the compiler can find 
the definitions of these functions: 


1. Create a Quick library containing the functions that are not listed 
(see Sections 10.1.1 and 10.1.3 for instructions). Then load this 
library when you start QuickC (Section 10.1.2). In this case, the 
missing function definitions are found in the Quick library. 
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2. Choose the Set Program List... command (Section 6.2.6) from the 
File menu to create a program list for the program. Then choose 
the Edit Program List... command (Section 6.2.8) to add the single 
module to the new program list and save the program list. In this 
case, the missing function definitions are found in the medium- 
model combined library MLIBCE.LIB on disk; see Section 6.1.4 


for more information about how QuickC uses program lists. 


6.1.2 Multiple-Module Programs 


You are required to create a program list for a multiple-module program 
so that the QuickC compiler will know which modules to use when 
building the program. Use the following general procedure to create a 
multiple-module program: 


1. Create, compile, and debug the source files that will make up the 
program using the following the steps: 


a. Choose the New command (Section 6.2.1) from the File menu 
to create a new source file, or choose the Open... command 
Section 6.2.2) from the File menu to open an existing source 
le for editing. 


b. Enter text for the source file using the editing keys and 
commands described in Chapter 7. 


c. Choose the Compile... command (Section 8.1.4) from the Run 
menu to compile the source file and verify that it is free of 
syntax errors. 


2. Choose the Set Program List... command (Section 6.2.6) from the 
File menu to create a program list for the program or load an 
existing file for editing. 


3. Choose the Edit Program List... command (Section 6.2.8) to add 
modules to or subtract modules from the program list and then 
save the program list. Note that you can also add object files or 
stand-alone libraries (libraries with .LIB extensions) to a pro- 
gram list. 


Repeat steps 1-3 as you develop additional program modules. 


5. Compile, run, and debug the program using the commands 
described in Chapter 8. 


When you compile a multiple-module program, QuickC checks the 
program list to see if any modules have been changed since the last time 
the program was compiled. If so, it recompiles the changed modules before 
rebuilding the program. This mechanism ensures that the program is 
always up to date with respect to its individual components. 
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The compiler saves the program list in a disk file with the same base name 
as the program and the extension .MAK. Outside of the QuickC 
environment, you can give the .MAK file as input to the MAKE utility to 
update the program. See Section 11.5 for more information about .MAK 
files. 


Note 


Do not delete the .MAK file for a program that has a program list. If 
you copy a program that has a program list to a different directory, 
you must also copy the .MAK file to the new directory. 


6.1.3. Working with Program Lists 


The QuickC compiler makes it easy to create and edit program lists. The 
following list outlines the operations you can perform on a program list 
and the commands you use to perform these operations: 


Operation Menu/Command 


Create a program list File/Set Program List... (Section 6.2.6) 
Open an existing File/Set Program List... (Section 6.2.6) 
program list for editing 

View contents of the File/Set Program List... (Section 6.2.6) or 
program list View/Source... (Section 5.1) 

Display or edit a View/Source... (Section 5.1) 

module in the program 

list 

Edit and save the File/Edit Program List... (Section 6.2.8) 
program list 

Clearing the current File/New (Section 6.2.1), File/Clear Pro- 
program list from gram List (Section eae or File/Edit Pro- 
memory gram List... with the Clear List command 


button (Section 6.2.8) 


If you ever lose track of the program list that is currently in memory, 
remember that the name of the program list (without the .MAK exten- 
gion) appears after the Program List: indicator on the status line at 
the bottom of the QuickC screen. 
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6.1.4 How QuickC Uses the Program List 


The QuickC compiler performs the following steps when it compiles a 
single-module program with a program list or rebuilds a multiple-module 
program: 


1. It recompiles any modules in the program list that have been 
updated since the last time the program was compiled. This creates 
updated object files on disk. 


2. It creates a linker response file with the same last name as the pro- 
gram and the extension .LNK. 


3. It invokes the linker, LINK.EXE. The linker links the object 
files created in step 1 with any other object files created from pro- 
gram modules and any object files or stand-alone libraries given in 
the program list, creating an executable file on disk. The linker 
looks for definitions of standard C-library routines in the following 
locations: 


e The core library that is built into the QuickC programming 
environment 


e The Quick library, if any, that is currently loaded 
e The stand-alone library MLIBCE.LIB on disk 


If the linker cannot find any of these routines, an error results and 
the program cannot be run. 


4, The compiler reloads the newly created executable file into the 
QuickO environment, where the program can be run. 


Note that the object files created in step 1, the linker-response file created 
in step 2, and the executable file created in step 3 are saved on disk. Other 
files may be saved on disk, depending on the options used to compile the 
program. For example, if you include debugging information in the pro- 
gram (see Section 8.1.4.3 for information on the Debug option), a map file 
is also saved. 


To control the operation of the linker in step 2, you can specify, in the 


-MAK file, any of the linker options described in Sections 9.5.1-9.5.14. 
See Section 11.5.3 for instructions. 


6.1.5 Common Questions About In-Memory 
Programs and Program Lists 


The questions and answers in this section summarize information about 
in-memory programs, program lists, and Quick libraries. 
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QUESTION: I get unresolved-external errors when I try to compile pro- 
grams in the QuickC environment. How can | solve these problems? 


ANSWER: The most common reason for getting unresolved-external 
errors for an in-memory program is that the program calls standard C 
library routines that are not in the QuickC core library (see Table 6.1). 


If your program uses standard library routines that are not listed in 
Table 6.1, employ either of the following methods: 


e Create a single-module program list that includes the name of the 
current program (see Sections 6.2.6-6.2.8). In this case, the linker 
resolves external references using the medium-model combined 


library MLIBCE.LIB on disk. 


e Build and load a Quick library containing the missing routines (see 
Sections 10.1.1-10.1.3). In this case, the functions in the Quick 
library resolve the external references. 


QUESTION: If my programs use functions that are not listed in Table 6.1, 
when is it better to create and load a program list and when is it better to 
create and load a Quick library? 


ANSWER: If you are running on a hard-disk system, it is usually easier 


to create a program list because this method saves the trouble of hav- 
ing to build a Quick library. Although the compiler must invoke the 
linker and go to the disk to find the functions that are not in the core 
library, the hard disk minimizes the amount of time needed for this 
process. 


If you are running on a floppy-disk system, it is usually preferable to 
create and load a Quick library containing the missing functions. This 
is because all of the functions that the program needs can be found in 
memory, either in the core library or in the Quick library, and there is 
no need to access the disk. 


QUESTION: How do I create a new program list? 
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ANSWER: Choose the Set Program List... command (Section 6.2.6) 


from the File menu, and give the name you have chosen for the new 
program list in the File Name text box. Usually, this is the base name 


of the program, with the extension .MAK. If this program list does 


not exist, QuickC asks if you want to create it; choose the Yes com- 
mand button. QuickC automatically executes the Edit Program List... 
command (Section 6.2.8) so that you can add modules to the new pro- 
gram list. After you have finished adding modules to the program list, 
choose the Save List command button to save the new list. 
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QUESTION: How can I easily move between modules in a program list? 
ANSWER: Choose the Source command from the View menu and 
select the module you want to edit. 

QUESTION: How do I remove a program list from memory once I’ve 

loaded it? 

ANSWER: Choose the Clear Program List command from the File 
menu. 

QUESTION: How do I create a Quick library? 


ANSWER: See Section 10.1.1 for instructions. The basic procedure 
is to 


1. Create a main program that calls the functions you want to put in 


the Quick library. 
Compile this program with the /c and /AM compiler options. 


3. Link the resulting file with the QUICKLIB.OBJ object file and 
the /QU linker option. 


QUESTION: How can I include an existing object file or stand-alone 
library in an in-memory program? 


ANSWER: Create a program list (Section 6.2.6) and add the object 
files or libraries to the program list (Section 6.2.8). Note that when you 
put a stand-alone library in the program list, the linker puts the com- 
plete contents of the library in the program. 


QUESTION: Since the linker links the modules in a program list, is there a 
way to specify options to control linker operations? 


ANSWER: Specify linker options (Sections 9.5.1-9.5.14) by using a 
macro named LDFLAGS in the. file that contains the program 
list. See Section 11.5.3 for instructions. 


6.2 Handling Source Files: 
the File Menu 


The commands on the File menu are used to create new files, load existing 
files for editing, create and save program lists, save edited files, combine 
files, and print files. 
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When you select File on the menu bar, the File menu shown below in Fig- 
ure 6.1 opens. 


Open... 

Open Last File 
Merge... 

Save 

Save As... 


Set Program List... 


Clear Program List 
Edit Program List... 


Print... 
DOS Shell 
Exit 


Figure 6.1 The File Menu 


The commands on the File menu perform the following actions: 


Command Action 

New Creates a new file. 

Open... Loads an existing file for editing. 

Open Last File Loads the most recently edited file and 


optionally saves the current file if it has been 
changed. The shortcut key for this command 
is F2. 


Merge... Copies a file from disk into the current file 
after the line on which the cursor is resting. 


Save Saves the file you were editing under its 
current name. 


Save As... Saves the file you were editing under a 
different name. 


Set Program List... Creates a new program list or loads an 
existing program list into the QuickC 
environment. 
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Clear Program List Removes the current program list from 
memory. 

Edit Program List... | Adds modules to or deletes modules from the 
current program list. 

Print... Prints selected text or the entire current file. 

DOS Shell Temporarily exits to DOS and later returns to 
QuickC. 

Exit Ends the QuickC session and exits to DOS. 


Sections 6.2.1-6.2.11 describe how to use each command on the File menu. 


6.2.1 Creating New Programs: 
the New Command 


The New command creates a new file in memory. This file may be any type 
of file, including a C source file, an include file, or a document. Assign a 
name to the file when you save it using the Save or Save As... command. 


The New command also clears the current program list from memory. Use 
the Set Program List... command (Section 6.2.6) to create a program list 
for the new program. 


6.2.2 Loading Files for Editing: 

the Open... Command 
The Open... command loads an existing file for editing. You can also 
use the Open... command to list files that are in different directories on 
your system. 


When you choose the Open... command from the File menu, the dialog 
box shown in Figure 6.2 opens. 
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Current path Type the file name or the file specification for the 
specification list box here. What you type replaces the selected text. 


backw.c 
backwZ.c 


bin_text.c 
blank.c 
bomb.c 
bubsort.c 
cflou.c 


File names that match the specification 
in the File Name text box 


Figure 6.2 The Open... Dialog Box 


Use the following options and displays in the dialog box to describe the file 
that you want to open: 


Option /Display Use 


File Name Type the name of the file that you want to open. 
If you would rather choose this file from the list 
box, type a specification for the files that you 
want to appear in the list box. See Section 
6.2.2.1, “Loading Files with Open...,” and Sec- 
tion 6.2.2.2, “Listing Files with Open...,” for 
more information. 


(Path specification) The current path specification appears between 
the File Name text box and the list box. 


(List box) Files that match the file and path specifications 
you typed appear in the File Name text box. 
Directory and file names are displayed alphabet- 
ically in columns. Names of directories are 
highlighted and appear in uppercase letters; file 
names appear in lowercase letters. 
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If the file names do not fit in the box, press the 
RIGHT or LEFT key to move the reverse-video 
highlight to the edge of the box and scroll the 
list. If you are using a mouse, use the scroll bar 
at the bottom of the list box to scroll the list to 
the left or right. See Section 6.2.2.1, “Loading 
Files with Open...,” and Section 6.2.2.2, “List- 
ing Files with Open...,” for more information. 


OK Choose this command button to open the file 
you have selected. 


Cancel Choose this command button to cancel the 
Open... command. 


When the Open... dialog box first appears, the file specification *.c 
appears highlighted in the text box. All files in the current directory that 
have the extension .C appear in the list box. 


6.2.2.1 Loading Files with Open... 
You can specify the file you want to load in one of the following ways: 


1. Type the name of the file, then press ENTER. QuickC assumes the 
.C extension for all file names without extensions. If you want to 
load a file that has no extension, type a period (.) immediately 
after the file name. 


2. Press the TAB key to move the input focus to the list box and use 
the DIRECTION keys to move through the list box until the file you 
want to load is highlighted. Then press ENTER to load the file. 


You can also type the first letter of the name of the file you want 
to load. This moves the highlight to the first file name or directory 
name in the list that begins with that letter. For example, if you 
are looking for the file PROG1.C, typing P moves the input focus 
to the first file name beginning with “P.” 


3. Using the mouse, double-click the file name in the list box. 


6.2.2.2 Listing Files with Open... 


You can use the text box on the Open... dialog box to list the contents of 
any directory on your system. 
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In the list box, file names appear in lowercase letters, and directory names 
appear in highlighted uppercase letters. The entry “..” in the upper-left 
corner of the list box represents the directory immediately above the 
current directory. When you enter a directory in the text box, or select a 
directory from the list box, QuickC lists the files in that directory. (When 
you select or enter a file name, the file is loaded into memory.) You can use 


the DOS wild-card characters (? and *) to list groups of files. 


6.2.3. Opening the Last Edited File: 
the Open Last File Command 


The Open Last File command loads the file you were most recently editing. 
If you have not saved changes to the current file, QuickC asks if you want 
to save it before loading the new file. If you have not edited other files 
since you started QuickC, no new file is loaded. 


If you are editing two source files, this command makes it easy to move 
back and forth between the two. After you save one source file and load a 
second source file for editing, the first source file becomes the “last file” 
edited. To reload this previously saved file for editing, simply choose Open 
Last File or press the F2 shortcut key again. 


6.2.4 Merging Files: the Merge... Command 
The Merge... command inserts a file beginning after the line on which the 


cursor is resting in the edit window. When you select Merge... from the 
File menu, the dialog box shown in Figure 6.3 opens. 


File Name: 


C:\SRC 


asZ-1.c . backw.c 
asZ-5.c - backw2.c 
as2-8.c . bin_text.c 
as3-l1.c 4 blank.c 
as3-Z.c H bomb.c 
as3-3.c ° bubsort.c 


Figure 6.3 The Merge... Dialog Box 
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The options in the Merge... dialog box are the same as the options in the 
Open... dialog box. See Section 6.2.2 for more information. 


6.2.5 Saving Files: the Save 
and Save As... Commands 


The Save and Save As... commands save the file you are editing in a disk 
file. Use the Save command to save the file under its original name or the 
Save As... command to change the file name. If you are saving a new, 
unnamed file, you can use either command to specify the file name. When 
you choose the Save As... command, the dialog box shown in Figure 6.4 
opens. 


File Name: | SRS e-yare 


C:\SRC 


Figure 6.4 The Save As... Dialog Box 


The Save As... dialog box has the following options and displays: 
Option /Display Use 


File Name If you are saving a new, unnamed file, enter the 
file name in the text box. If you are saving a file 
that already has a name, the file name appears 
in the text box. To use the same file name, just 
press ENTER. To change the file name, begin 
typing. What you type replaces the old name. 


(Path specification) The current path specification appears between 
the File Name text box and the command but- 
tons. 


OK Choose this command button to save the file 
with the name given in the text box. 


Cancel Choose this command button to cancel the Save 
As... command and return to the editor. 
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6.2.6 Creating and Loading Program Lists: | 
the Set Program List... Command 


The Set Program List... command creates a new program list or loads an 
existing program list into the QuickC environment. 


When you choose the Set Program List... command, a dialog box similar 
to the Open... dialog box (Figure 6.2) appears, except that the file 
specification in the File Name list box is *«.mak. (Recall that program 
lists are saved in files with extensions of .MAK.) You can choose a .MAK 
file for editing or display the .MAK files in any directory on your system, 
just as you do for the Open... command; see Sections 6.2.2.1-6.2.2.2 for 
details. If you choose an existing MAK file for editing, use the Edit Pro- 
gram List... command to make the changes to the file. 


If you give the name of a nonexistent .MAK file, QuickC asks if you want 
to create the file. If you respond with “Yes,” Quick automatically opens 
the dialog box for the Edit Program List... command so that you can add 
modules to the new program list. 


After you load a program list, the name of the program list appears after 


the Program List: indicator on the status line. 


When you compile, the Build Program and Rebuild All command buttons 
affect only the modules in this program list, not the source file you are 
editing. 


6.2.7 Clearing the Current Program List: 
the Clear Program List Command 


The Clear Program List command clears the current program list from 
memory. The Program List: indicator in the status line is changed to 
read <none> to indicate that no program list is currently in memory. 
Until you load a new program list with the Set Program List... command, 
the QuickC compiler assumes that any source files you compile are single- 
module files that are not part of a program list. 


6.2.8 Editing the Program List: 
the Edit Program List... Command 


The Edit Program List... command maintains the list of modules that 
comprise a program. 
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When you select Edit Program List... from the File menu, or after you _ 
create a new program list with the Set Program List... command, the dia- 
log box shown in Figure 6.5 opens. 


Current path Type the file name or the file specification for the 
specification | list box here. What you type replaces the selected text. 


File Name: 


as1@-5.c 
asll-1.c 
as11-S.c 
asii-6.c 
asZ-1.c 


Program List: 


gettoken.c 


File names that match the specification File names in the 
in the File Name text box current program list 


Figure 6.5 The Edit Program List... Dialog Box 


Use the following options and displays in the Edit Program List... dialog 
box to specify the program list you want to change and the changes you 
want to make: 


Option /Display Use 


File Name Type the name of the .MAK file containing 
the program list you want to edit, or type a 
specification for the files that you want to list" 
in the list box. You can use the Edit Program 
List... command in the same way you use the 
Open... command to list files on the current 
drive or in the current directory; see Section 
6.2.2.1, “Loading Files with Open...,” and 
Section 6.2.2.2, “Listing Files with Open...,” 
for details. 
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(Path specification) 


Files 


Program List 


Add/Remove 


Clear List 


Save List 


Cancel 
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The current path specification appears be- 
tween the File Name text box and the com- 
mand buttons. 


This list box shows all disk files that match 
the file and path specifications you have 
given in the File Name text box. When you 
select a file name in the list box, choose the 
Add/Remove command button to add the file 
to, or delete the file from, the program list. 
You can select files from the list box or 
display files in different directories just as you 
do for the Open... command on the File 
menu. See Section 6.2.2.1, “Loading Files 
with Open...,” and Section 6.2.2.2, “Listing 
Files with Open...,” for details. 


This list box shows all modules associated 
with the program list that is currently loaded. 
Choose files to be deleted from the program 
list the same as you choose files for the 
Open... command; see Section 6.2.2.1, “Load- 
ing Files with Open...,” for details. 


Choose this command button to add the 
selected file to the program list or remove it 
from the list. If the file is not already in the 
program list, it is added to the list. If the file 
is already in the program list, it is deleted 
from the list. The program list is not actually 
changed until you choose the Save List com- 
mand button. 


Choose this command button to remove all 
modules from the current program list. 


Note that this command button removes all 
modules from the program list whether or not 
you choose the Save List command button; 
the Cancel command button does not restore 
the original program list. 


Choose this command button to save all 
changes to the program list in the .MAK file 
for the program. 


Choose this command button to cancel the 
Edit Program List... command. 
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Use the following procedure to edit the program list: 


Select the Edit Program List... command from the File menu. 


Choose the directory from which you want to add files to the pro- 
gram list. See Section 6.2.2.1, “Loading Files with Open...,” and 
Section 6.2.2.2, “Listing Files with Open...,” for instructions. 


3. Choose a file from the Files list box to be added to or deleted from 
the list. 


4. Press ENTER. If the file you chose is not in the Program List list 
box, QuickC adds it. If it is already in the Program List list box, 
QuickC removes it from that list box. The dialog box remains on 
the screen. 


5. Repeat steps 4-5 until the Program List box contains the files 
you want. 


6. Type ALT+S to save the program list and update the program 
~ .MAK file, or type ALT+C to clear the program list. The dialog box 
disappears from the screen. 


Press ESC or choose the Cancel command button at any time to cancel the 
Edit Program List... command. 


6.2.9 Printing Files: the Print. .. Command 


The Print... command prints either the file you are editing or selected text 
from that file. Files are printed without page breaks or headings. 


To use this command, your printer must be connected to LPT1. (Alterna- 
a ." can use the DOS MODE command to redirect LPT1 to 
OM1. 


When you choose the Print... command from the File menu, the dialog 
box shown in Figure 6.6 opens. 


(>) Print File 
( >) Print Selected Text 


Figure 6.6 The Print... Dialog Box 
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You can select either of the following print options: 
Option Use 


Print File Prints the contents of the file you are editing 


Print Selected Text Prints only the text selected (highlighted) in the 
view window 


While the file is printing, a dialog box with a Cancel command button 
appears on the screen. To stop printing, simply press ESC or SPACEBAR. 


6.2.10 Temporarily Returning to DOS: 
the DOS Shell Command 


The DOS Shell command lets you temporarily return to the DOS com- 
mand level, where you can execute other programs and DOS commands. 
QuickC remains in memory. Note that you should not delete .MAK files, 
C source files, or files in the current program list before you return to 
QuickC. 


QuickC needs to be able to find the COMMAND.COM file before it 
can execute the DOS Shell command. QuickC first looks in the directory 
given in the COMSPEC environment variable, then in the current direc- 
tory. See your DOS user documentation for more information about 


COMMAND.COM and COMSPEC. 


To return to QuickC from the DOS command level, execute the DOS 
EXIT command. 


6.2.11 Leaving QuickC: 
the Exit Command 


The Exit command removes QuickC from memory and then returns you 


to DOS. 


If you have been editing a file but have not saved it, a prompt asks you if 
you want to save the program. To save the program, press ENTER or click 
the Yes button with the mouse. If the program has no name, the Save 
As... dialog box appears. 


To return to the system without saving the file, type n or click the No 
button with the mouse. 
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The program editor built into the QuickC programming environment pro- 
vides a powerful, flexible set of keyboard and menu commands for editing 
source files. Most QuickC editing operations require only a single key- 
stroke or a single key sequence using the ALT, CTRL, or SHIFT key. Using 
the QuickC editor, you can quickly perform editing operations such as 
moving the cursor; selecting, inserting, copying, and deleting text; and 
opening new lines in the source file. 


Note 


If you have used the MicroPro WordStare program, you will find that 
many of the QuickC editing commands are the same as the commands 
used in WordStar. 


This section describes how to enter and edit program text using the 
QuickC editor commands and the Edit and Search menus. 


e Section 7.1 presents the keyboard and mouse editing commands. 


e Sections 7.2 and 7.3 describe the commands on the two editing 
menus, Edit and Search. 


7.1 Editing with the Keyboard and Mouse 


When you want to edit text, simply follow these steps: 


1. Move the cursor to the beginning of the text you want to edit. 


2. Select the text you want to edit. Press the SHIFT key plus any 
cursor-movement key to select text. 


3. Edit the selected text. 


7.1.1 Using QuickC Editing Keys 


Table 7.1 describes the keyboard commands that move the cursor, select 
text, and perform editing functions. 
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Table 7.1 | 
QuickC Editing Keys 


To Move the Cursor: 


Up/down one line 
Right /left one character 


Left one character (delete 
character) 


Right /left one word 


To beginning/end of the line 
To top/bottom of the screen 
To beginning/end of the file 


To next error 
To previous error 


To Scroll: 


Up/down one line 
Up/down one window 
Left/right one window 


To Select Text: 


Character 


Current line 
and line above/below 


Word 
Screen 
To beginning/end of the file 


To Insert: 
Text from the Clipboard 


(see Section 7.2) 
Line above the current line 
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Press: 


UP or CTRL+E / DOWN or CTRL+X 
RIGHT or CTRL+D / LEFT or CTRL+S 
BACKSPACE or CTRL+H 


CTRL+RIGHT or CTRL+F / CTRL+LEFT or 
CTRL+A 


HOME or CTRL+Q 5S / END or CTRL+QD 
CTRL+QE / CTRL+Q X 


CTRL+HOME or CTRL+QR / CTRL+END 
or CTRL+Q C 


SHIFT+F3 
SHIFT+F4 


Press: 


CTRL+W / CTRL+Z 
PGUP or CTRL+R / PGDN or CTRL+C 


’ CTRL+PGUP / CTRL+PGDN 


Press: 
SHIFT+LEFT / SHIFT+RIGHT 


SHIFT+UP / SHIFT+DOWN 
SHIFT+CTRL+LEFT / SHIFT+CTRL+RIGHT 
SHIFT+PGUP / SHIFT+PGDN 
SHIFT+CTRL+HOME / SHIFT+CTRL+END. 


Press: 
SHIFT+INS 


CTRL+N 


Table 7.1 (continued) 
To Insert: 


Tab at the current cursor 
position 


Tab at the beginning of 
each selected line (when 
one or more lines are 
selected) 


Control character 
To Delete: 


Character where cursor 
1s resting 


Word 


Current line, saving in 
Clipboard (see Section 7.2) 


To end of line 

Selected text 

Selected text, not saving in 
Clipboard 

Character left of cursor 


To Copy: 


Selected text, saving in 
Clipboard (see Section 7.2) 


To Tab: 
All selected text right/left 
To Break a Line: 


At the current location 


7.1.2 Using Insert and Overtype Modes 


Press: 


TAB or CTRL+I 


TAB 


CTRL+P, followed by CTRL+character 


Press: 


DEL or CTRL+G 
CTRL+T 
CTRL+Y 


CTRL+Q Y 
SHIFT+DEL 
DEL 


BACKSPACE or CTRL+H 
Press: 


CTRL+INS 


Press: 
TAB / SHIFT+TAB 
Press: 


ENTER 


Editing Source Files 


The QuickC editor operates in one of two modes: insert mode or overtype 
mode. When the editor is in “insert” mode, typed characters are inserted 
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to the left of the cursor. When the editor is in “overtype” mode, typed 
characters overwrite the characters on the current line. 


Use the INS key or the CTRL+V key sequence to toggle the editor between 
insert mode and overtype mode. When overtype mode is on, the cursor 
becomes a block. 


In insert mode, the editor inserts a typed character at the cursor position. 
In overtype mode, the editor replaces the character under the cursor with 
the character you type. Insert mode is the default mode. 


7.1.3 Using Place Markers in Text 


If you are working on different parts of a large file, you can set place mark- 
ers at different places in the file, then jump to each place marker when you 
need to work on that part of the file again. You can set up to four place 
markers, numbered 0 through 3, in any source file. To use place markers: 

e Press CTRL+K nto set place-marker number n. 


e Press CTRL+Q nto move the cursor to place-marker number n. 


7.1.4 Matching Braces 

The QuickC editor provides a simple solution to a common problem in 
editing C source files: finding the matching left or right brace ({ }), 
bracket ([ ); angle bracket (< >), or parenthesis ()). To find a match- 
ing brace, bracket, angle bracket, or parenthesis, follow these steps: 


1. Move the cursor to the brace, bracket, angle bracket, or 
parenthesis you want to match. 


2. Press CTRL+] or CTRL+(. 


7.1.5 Editing with the Mouse 


Using the mouse, you can move the cursor and select text quickly, then use 
the keyboard to perform the desired editing function. 


To move the cursor with the mouse, position the mouse pointer where you 
want the cursor and click the left button. 


Table 7.2 describes ways to select text with the mouse. 
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Table 7.2 
Selecting Text with a Mouse 


To Select: Do This: 


A character Point to the character to the right of the character 
you want to select, press the left button, and drag 
the pointer left over the character or characters you 
want to select. Dragging right selects the character 
the cursor is on. 


A word Double-click the word. 


A line Point to the first column of the line, press the left 
button, drag the highlight down one line and release 
the button. Dragging up selects the line above the 
cursor. 


Several lines _—_ Point to the first line you want to select, then press 
the left button and drag the highlight up or down 
through the lines you want to select. 


If you make a mistake while selecting text, click the selected text to cancel 
the selection. 


7.2 Editing Commands: the Edit Menu 


Figure 7.1 shows the Edit menu. The commands in the Edit menu let you 
delete, move, or copy text from your program and undo modifications to 
the current line. 


Read Only 


Figure 7.1 The Edit Menu 
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Use the following commands from the Edit menu to edit the contents of 
your source file: 


Command Action 

Undo Reverses any changes to the current line. The 
shortcut key sequence for this command is 
ALT+BACKSPACE. 

Cut Deletes the selected text and places it in the Clip- 


board. The “Clipboard” is a temporary storage 
area that the QuickC editor uses to hold copied or 
deleted text. The shortcut key for this command is 
SHIFT+DEL. 


Copy Copies the selected text and places it in the Clip- 
board, leaving the copied text in its original loca- 
tion. The shortcut key sequence for this command 
is CTRL+INS. 


Paste Inserts text from the Clipboard into the file you 
are editing. The shortcut key sequence for this 
command is SHIFT+INS. 


Clear Removes the selected text but does not put it in 
the Clipboard. The shortcut key sequence for this 
command is DEL. 


Read Only Places the editor in read-only mode and prevents 
changes to the current file. 


Sections 7.2.1-7.2.3 describe the Edit menu commands in detail. 


7.2.1 Undoing Edits: the Undo Command 


The Undo command reverses changes to the current line. You can restore a 
line as long as the cursor is on it. When you move the cursor off the line, 
the changes are permanent. 


Undo is turned off until the current line is modified. When these com- 
mands are turned off, no letter is highlighted in the command name on the 
menu. If you choose Undo while it is turned off, nothing happens. 


You cannot use Undo to restore lines deleted with the CTRL+Y key 
sequence. Use CTRL+Q L or CTRL+INS instead. 
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7.2.2 Deleting and Inserting Text: the Cut, 
Copy, Paste, and Clear Commands 


Use the Cut, Copy, Paste, and Clear commands to move, copy, delete, or 
insert text in the source file you are editing. 


The Cut, Copy, and Clear commands all affect the currently selected text. 
For various editing tasks, use combinations of the following commands: 


e Use the Cut command, along with the Paste command (see below), 
to move text to a different place in the file. The Cut command 
deletes the selected text and places it in the Clipboard. The previ- 
ous contents of the Clipboard are deleted. 


e Use the Copy command to copy text to a different place in the file. 
The Copy command leaves the selected text in place and copies it 
to the Clipboard. The previous contents of the Clipboard are 
deleted. 


e Use the Clear command to remove text from the file. The Clear 
command deletes the selected text but does not place it in the Clip- 
board. 


Note 


If you are moving text to a different place in the file, it is safest to use 
the Paste command immediately after you select Cut or Copy. This 
will ensure that you don’t accidentally remove the text you are moving 
from the Clipboard. 


Until text is selected, the Cut, Copy, and Clear commands are turned off; 
no letter is highlighted in the command name on the menu. If you choose 
any of these commands while they are turned off, nothing happens. 


‘The Paste command inserts text from the Clipboard. One handy use for 
this command is to replace text that you have selected in the view window: 
when you choose Paste, the contents of the the Clipboard replace the 
selected text. If no text is selected, the Paste command inserts the con- 
tents of the Clipboard to the left of the cursor. You can paste the same 
information from the Clipboard as many times as you want. If no text is in 
the Clipboard, Paste is turned off. 


To insert text from the Clipboard, follow these steps: 
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1. Move the cursor to the place you want the text inserted. The text 
is inserted to the left of the cursor. If you want to replace text with 
the contents of the Clipboard, select the text to be replaced. 


2. Choose Paste from the Edit menu. 


Text remains in the Clipboard until you end your QuickC session. (The 
New and Open... commands don’t erase the Clipboard.) If you run out of 
memory during compilation, erase the Clipboard by copying something 
small into it, such as a single character. 


7.2.3 Setting Read-Only Mode: 
the Read Only Command 


The Read Only command turns read-only mode on and off. When the edi- 
tor is in read-only mode, no changes can be made to the currently loaded 
file; an R appears on the status line and a check mark appears next to the 
Read Only command on the Edit menu. 


This command is useful during debugging. Ordinarily, if you accidentally 
change the file during debugging, a prompt asks if you want to recompile 
the program before proceeding with program execution. Selecting the 
ied command prevents you from making such accidental changes to 
the file. 


7.3 Searching For and Replacing Text: 
the Search Menu 


Figure 7.2 shows the Search menu. You can find specific parts of your pro- 
gram by using commands from the Search menu. 


Search 


Find.2. 
Selected Text Ctri+ 


Repeat Last Find F3 
Change.. 
Function 


- Next Error Shift+F3 
Previous Error Shift+F4 


Figure 7.2 The Search Menu 
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The commands in the Search menu perform the following actions: 


Command 


Find... 


Selected Text 


Repeat Last Find 


Change... 


Function 
Next Error 


Previous Error 


Action 


Finds the first occurrence of the text you. 
specify. The shortcut key sequence for this com- 
mand is CTRL+\ or CTRL+QF. 


Finds text you selected from the view window. 
The shortcut key sequence for this command is 
CTRL+\. 


Finds the next occurrence of the text you 
specified in a previous search command. The 
shortcut key for this command is F3; the 
shortcut key sequence is CTRL+L. 


Finds specified text and replaces it with different 
text. The shortcut key sequence for this com- 
mand is CTRL+Q A. 


Finds a specified function during debugging. 


Finds the source line containing the next error. 
The shortcut key sequence for this command is 
SHIFT+F3. 


Finds the source line containing the previous 
error. The shortcut key sequence for this com- 
mand is SHIFT+F4. 


Searches begin at the cursor and “wrap around” the top of the view win- 
dow to the starting point of the search. All the commands on the Search 
menu search for the text you last specified in a search command, unless 


you specify otherwise. 


The following sections describe the Search menu commands in detail. 


7.3.1 Finding Text: the Find..., Selected Text, 
and Repeat Last Find Commands 


The QuickC editor provides the following ways to search for text: 


e Select the Find... command and specify the text you are search- 


ing for. 


e Select the text in the view window and search for it using the 
Selected Text command. 


e Search for the next instance of the same text using the Repeat Last 


Find command. 
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Sections 7.3.1.1-7.3.1.4 describe these commands. 


7.3.1.1 The Find... Command 


Use the Find... command to search for a character, a word, or groups of 
characters and words in your program. The shortcut key sequence for this 
command is CTRL+Q F; in cases where no text is currently selected, another 
shortcut key sequence is CTRL+\. 


When you choose the Find... command, the Find... dialog box shown in 


Figure 7.3 opens. 


C 1 Whole Word 
C ] Match Upper/Lowercase 
C J] Regular Expression 


Figure 7.3 The Find... Dialog Box 


The following list explains the options on the Find... dialog box: 
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Option 
Find What 


Whole Word 


Use 


Choose this text box to highlight the text 
you last searched for. If you are searching 
for different text, type the text you are 
searching for. 


Choose this text box to find the specified 


text only if it is surrounded by spaces, 
punctuation marks, or other characters not 


considered parts of a word. Characters con- 
sidered as part of a word include uppercase 
letters (A—Z), lowercase letters (a—z), digits 
(0-9), and the underscore (— ), which is 
commonly used in variable declarations. 
For example, if define is the specified 
text, the Whole Word option will locate 
#define but not define_terms. © 
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Match Upper/Lowercase Choose this check box if you want to find 
only instances of the specified text that 
match exactly. For example, if DEFINE is 
the specified text, the Match 
Upper/Lowercase option will find DEFINE 
but not define. 


Regular Expression Choose this check box if you want to use 
special characters to generalize the text you 
are searching for. See Section 7.3.1.4, “Spe- 
cial Characters in Regular Expressions,” 
for a list of regular expressions. 


OK Choose this command button to start the 
search for the next occurrence of the 
specified text. 


Cancel Choose this command button to cancel the 
selections in the Find... dialog box and 
return to the view window. 


If the text isn’t found, a box appears that says Match Not Found. To 
remove the box and continue, either press ENTER or SPACEBAR, or click the 
OK command box with the mouse. 


7.3.1.2 Finding Selected Text: the Selected Text Command 


Another way to search for text in a program is to use the Selected Text 
command. Instead of typing the text you want to search for, you can sim- 
ply highlight the text you want to search for in the view window. Follow 
these steps to use the Selected Text command: 


1. Select the text you wish to search for. Selected text must be on a 
single line. 
2. Choose the Selected Text command from the Search menu. 
The highlight moves to the next occurrence of the selected text. If no text 


is selected, this command behaves the same as the Find... command. The 
shortcut key sequence for Selected Text is CTRL+\. 


7.3.1.3 The Repeat Last Find Command 
The Repeat Last Find command searches for the text specified in the most 


recent Find..., Selected Text, or Change command. The shortcut key for 
Repeat Last Find is F3; the shortcut key sequence is CTRL+L. 
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7.3.1.4 Special Characters in Regular Expressions 


If you select the Regular Expressions check box in the Find... dialog box, 
you can use the the following characters to specify text patterns in 
searches for text on a line: 


Character Meaning 

Period (.) Matches any single character. 

Caret (*) Matches text that appears at the beginning of 
a line. 

Dollar sign ($) Matches text that appears at the end of a 


line. The dollar sign must appear at the end 
of the text being searched for. 


Asterisk (*) Matches zero or more repetitions of the char- 
acter preceding the asterisk. For example, _* 
finds any sequence of one or more under- 
scores. 


Brackets ([ ]) Matches sets of the characters specified within 
the brackets. To match a right-bracket char- 
acter, type it immediately after the left 
bracket that delimits the set of characters. 
The following special characters may be used 
inside brackets: 


Character Use 


Caret (*) Matches any character 
except those specified within 
the brackets. Must be the 
first character within brack- 
ets to be treated as a special 
character. 


Dash (—) Matches characters in ASCII 
order between the charac- 
ters on either side of the 
dash, including the delimit- 
ing characters. 


Backslash (\) Characters preceded by a backslash lose their 
special meanings and are treated literally. For 
example, to match a dollar sign instead of 
using the dollar sign to represent the end of 
the line, type \$. 


Note that using special characters in search text uses additional memory. 
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m Examples 


The following examples illustrate the uses of special characters in regular 
expressions: 


ItJ 

I\+J 

In the example above, the first regular expression matches such combina- 
tions as IJ, IIJ, and IIIJ. The second regular expression matches only 


I*J. The backslash is necessary because the asterisk (*) is a special char- 
acter in regular expressions. 


x[-+/*]y 

In the example above, the regular expression matches xty, x-y, x/y, or 
xxy, but not x=y or xzy. 

[A-Za-z ] 

The regular expression above matches any uppercase letter, lowercase 
letter, or space. 

[“O-9] 


The regular expression above matches any character other than a digit. 


[]#! [@%] 


The regular expression above matches either a left or a right bracket, or 
any of the other characters delimited by the first left bracket and the last 
right bracket. The first right bracket is not treated as a special character, 
since it appears immediately after the initial left bracket. 


\C[O-9] #\] 


The regular expression above matches strings of numbers that appear 
within brackets. 
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7.3.2 Replacing Text: 
the Change... Command 


Use the Change... command to search for text and replace it with 
different text. The shortcut key sequence for this command is CTRL+Q A. 
When you choose the Change... command, the dialog box shown in Figure 
7.4 opens. 


C J Whole Word 
{ J] Match Upper/Lovercase 
C 1 Regular Expression 


Find and Verify Change All 


Figure 7.4 The Change... Dialog Box 


The Find What, Whole Word, Match Upper/Lowercase, Regular Expres- 
sion, and Cancel options have the same uses as they have in the Find... 
command; see Section 7.3.1.1, “The Find... Command,” and Section 
7.3.1.4, “Special Characters in Regular Expressions,” for details. The fol- 
lowing list describes the remaining options in the Change... dialog box: 


Option Use 
Change To Type the replacement text in this text box. 
Find and Verify Select this command button if you want to 


confirm each change before the QuickC editor 
makes it. When you select this command but- 
ton, the editor finds the text, then displays three 
more command buttons: Change, Skip, and 
Cancel. These command buttons are shown 
below: 
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Select the Change command button to make the 
change; select the Skip command button to 
leave the text as it is and search for the next 
occurrence of the specified text; or select the 
Cancel command button to stop the search and 
return to the view window. 


Change All Select this command button if you want to 
replace all occurrences of the specified text 
without having to confirm each change. 


Note 


If you use the Change command to change text, you cannot undo your 
changes with the Undo command from the Edit menu. 


7.3.3 Finding Functions: the Function Command 

The Function command finds the entry point of a given function in the file 
you are editing. Before you use this command, compile the current source 
file with the Debug option selected. 


When you choose the Function command, the dialog box shown in Figure 
7.5 appears. 


Figure 7.5 The Function Dialog Box 


Type the function name in the Function text box. If you have selected a 
function name, that name automatically appears in the text box. Then 
select the OIC command button to find that function, or select the Cancel 
command button to cancel the command. 
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7.3.4 Finding Program Errors: the Next Error 
and Previous Error Commands 


Use the Next Error and Previous Error commands to quickly find and 
correct syntax errors in your programs. The shortcut key sequence for 
Next Error is SHIFT+F3; the shortcut key sequence for Previous Error is 
SHIFT+F4. 


If your program has compilation errors, QuickC creates a list of these 
errors in order of appearance and opens a window at the bottom of the 
screen to display the errors. For each error that it displays, QuickC indi- 
cates how many errors are in the list and where the error falls in the list. 
For example, if a program has generated six errors and the fourth error is 
being displayed, the message (4 of 6) appears after the error message. 


If you choose Next Error while QuickC is displaying the last error in the 
list, a beep indicates that it is at the end of the list. If you choose Next 
Error a second time, QuickC displays the first error in the list. Similarly, if 
you choose Previous Error while QuickC is displaying the first error in the 
list, a beep indicates that it is at the beginning of the list. If you choose 
Previous Error a second time, QuickC displays the last error in the list. 


The Next Error command moves the cursor to the line in the program that 
caused the next error in the list and displays the corresponding error mes- 
sage in the error window. Similarly, the Previous Error command moves 
the cursor to the line that caused the previous error in the list and dis- 
plays the previous error message. If the error occurred in an include file, 
the QuickC editor displays the include file and moves the cursor to the line 
in the include file that caused the error. 


Note 


Error messages may appear without text if there is insufficient memory 
to load the error-message text. 


The QuickC compiler saves the first 26 errors during compilation. Thus, 
you may still get errors after you have corrected all of the errors that 
QuickC displays for a single compilation. 


See Appendix D of this manual for lists and descriptions of QuickC error 
messages. . 
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The compiler and debugger included with Microsoft QuickC provide — 
powerful, flexible development tools that will help you get programs up 
and running—fast. This chapter will show you how to 


e Compile and execute QuickC programs 


e Choose compile-time and run-time options for programs 


e Create object and executable files on disk 


e Control program execution during debugging 


8.1 Compiling and Running Programs: 


the Run Menu 


You compile and execute programs with commands from the Run menu, 


shown in Figure 8.1. 


Start Shift+FS 


Restart 


Continue FS 
Compile... 
Set Runtime Options 


Figure 8.1 The Run Menu 


The commands in the Run menu perform the following actions: 


Command 


Start 


Restart 


Continue 


Action 


Compiles and runs the program currently 
being edited or defined by the current pro- 
gram list. The shortest key sequence for this 
command is SHIFT+F5. 


Resets the program so that the first statement 
in the main program is the next statement to 
be executed. 


Resumes execution of a stopped program. If 
you have edited the program, this command 
allows you to recompile it before resuming 
execution. The shortcut key for this command 
is FS. 
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Compile... Sets compile-time options for the program, 
compiles the program, and creates either a 
program that can be run within the QuickC 
environment or an object or executable file 


on disk. 
Set Runtime Sets run-time options for the program includ- 
Options... ing stack size, default-data-segment size, and 


values to be passed to the program through 
the argu and argc arguments to the main 
function. 


Sections 8.1.1—8.1.5 describe the commands on the Run menu. 


8.1.1 Running Programs: the Start Command 


The Start command runs the program you are editing or the program 
defined by the program list, beginnning with the first statement in the 
main program. If you have changed any modules since the last time you 
compiled the program, this command automatically recompiles these 
modules and recreates the program. 


8.1.2 Getting Programs Ready to Rerun: 
the Restart Command 


The Restart command resets the program so that the first statement in 
the main program is the next statement to be executed. This command is 
useful if you want to restart program execution after any of the following: 


e You have been single-stepping through the program during debug- 
ging. (See Section 8.2.2 for information about the QuickC com- 
mands that perform single-stepping. ) 


e The program has temporarily stopped at a breakpoint. (See Section 
8.2.1.2 for information about breakpoints). 


e The program has completed execution normally. 
After a Restart command, the next Start or Continue command executes 
the first statement in the main program. A Restart command does not 
actually start program execution. 


During debugging, use this command after you have edited the program to 
correct errors and then recompiled. 
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8.1.3 Continuing Program Execution: 
the Continue Command 


The Continue command resumes execution of a stopped program, begin- 
ning with the statement following the most recently executed statement. 
Use this command after executing a statement during single-stepping or 
after the program has stopped for a breakpoint. 


If you have changed the program, QuickC automatically recompiles the 
program before continuing execution. 


8.1.4 Controlling Compile-Time Options: 
the Compile... Command 


The Compile... command compiles the source file in the view window or 
the modules in the current program list. Use the options of this command 
to control how the program will behave after it is compiled. 


When you select Compile... from the Run menu the dialog box shown in 
Figure 8.2 opens. 


Name of file you are working on Define constants or macros 
Name of current program list Directories to search for include files 


Program List: Lexer 
Current File: C:\SRC\lexer.c 


Warning Levels Output Options Miscellaneous 
(+) Level @ ¢ ) Obj Debug 
¢ ) Level 1 C+) Memory Pointer Check 
€ ) Level 2 C ) Exe Stack Check 
( ) Level 3 ¢ ) Syntax Check Only Language Extensions 
Optimizations 


Include: 


Define: 


Build Program Compile File Rebuild All 


Compile changed Compile file you |Compile all modules 
modules in program list —\are working on in program list 


Figure 8.2 The Compile... Dialog Box 
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Sections 8.1.4.1-8.1.4.10 describe the options of this command and the 
effects these options have on program behavior. 


These options are saved in the QC.INI file, so that the default options 
used at the end of a QuickC session are used as the defaults for the next 
QuickC session. Also, for multiple-module programs and single-module 
programs that have a program list, the options used to compile the pro- 
gram are saved in the .MAK file that contains the program list. This 
ensures that these options are used if you rebuild the program within the 
QuickC environment or use the MAKE utility to update the program out- 
side the QuickC environment. 


8.1.4.1 Suppressing Compiler Warnings: 
the Warning Levels Options 


Choose one of the Warning Levels circular buttons to suppress compiler 
warning messages. Compiler warning messages are any messages beginning 
with the prefix C4; see Section D.1.3 for a full listing of these messages. 
Warnings indicate potential problems, rather than actual errors. 


The Warning Levels options have the following effects: 
Option Effect 


Level 0 Turns off all warning messages. This option is use- 
. ful when you compile programs that deliberately 
include questionable statements. 


Level 1 Causes the compiler to display most warning mes- 
sages. This option is the default. 


Level 2 Causes the compiler to display an intermediate 
level of warning messages. These warnings may or 

may not indicate serious problems. They are gen- 
erated when, for example, functions do not have a 
declared return type; return statements are miss- 
ing from functions with non-void return types; 
and data conversions occur that would cause loss 
of data or precision. 


Level 3 Displays the highest level of warning messages, 
including warnings about using non-ANSI features 
and extended keywords, and calling functions 
before function prototypes appear in the program. 
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Note that the descriptions of the warning messages in Appendix D, 
“Error-Message Reference,” indicate the warning level that must be set 
Mae is, the number for the appropriate Warning Levels option) in order 
or the message to appear. 


8.1.4.2 Choosing Output-File Format: 
Output Options 


Choose one of the Output Options circular buttons to specify what kind of 
file is created when you compile the source file you are editing or the 
modules in the current program list. The following list describes these 
options: 


Option Use 


Obj Creates an object file on disk with the same 
base name as the source file you are editing 
plus the extension .OBJ. 


Memory Creates a program that can be run within the 
QuickC environment. If you do not choose 
one of the output options, Memory is the 
default. 


Exe Creates an executable file on disk with the 
same base name as the current program plus 
the extension .EXE. This executable file can- 
not be run under QuickC, but it can be run, 
like any other program, from the DOS com- 
mand level. 


Syntax Check Only Checks the syntax of the program and dis- 
plays diagnostic messages for any errors 
found, but does not create an object or exe- 
cutable file. 


8.1.4.3 Preparing for Debugging: the Debug Option 
Choose the Debug check box if you want to debug your program within 
QuickC. The Debug option produces a program containing full symbolic- 


debugging information for use with in-memory debugging. 


If you choose this option and then choose the Build Program or Rebuild 
All command button (Section 8.1.4.10), the linker creates a map file on 


167 


Microsoft QuickC Compiler Programmer’s Guide 


disk containing the debugging information. This file has the same base 
name as the program and the extension .MAP. See Section 9.5.10 for 
information about map files and their formats. 


If you choose the Exe output option with the Debug option, the executable 
file you create is suitable for debugging using the Microsofte CodeViewe 
window-oriented debugger. 


8.1.4.4 Using “Smart Pointers”: the Pointer Check Option 


The Pointer Check check box protects your program from common pointer 
errors that do not otherwise cause run-time errors. When you choose 
Pointer Check, the QuickC compiler generates run-time code that verifies 
that pointer values address program data before the pointers are used. If 
not, QuickC displays a run-time error in the error window. 


Pointer checking can prevent errors that might overwrite QuickC or DOS 
code or data and cause QuickC or DOS to stop running. As a result, the 
use of this option is strongly recommended during program development. 


Note that the Pointer Check option may significantly slow program execu- 
tion. An alternative to using Pointer Check is to turn pointer checking on 
or off only for selected pointers, leaving the default (see below) for the 
remaining pointers in the module. When you want to turn on pointer 
checking, put the following line before the declaration of the pointer you 
want to check: 


# pragma check_ pointer (on) 


This line turns on pointer checking for all pointers that follow it in the 
source file, not just the pointers on the following line. To turn off pointer 
checking, insert the following line: 


# pragma check_ pointer (off) 


If no argument is given for the check_ pointer pragma, pointer checking 
reverts to the behavior specified by the Pointer Check option: turned on if 
the Pointer Check option is turned on, or turned off otherwise. The inter- 
action of the check_ pointer pragma ‘with the Pointer Check option is 
explained in greater detail in Table 8.1. 


168 


Compiling, Running, and Debugging Programs 


Table 8.1 
Using the check_ pointer Pragma 
Compiled with 

Syntax Pointer Check? Action 

# pragma check_ pointer() Yes Turns on checking for 
pointers that follow 

# pragma check_ pointer() No Turns off checking for 
pointers that follow 

# pragma check_pointer(on) Yes or no Turns on pointer 


checking for pointers 
that follow 

# pragma check_pointer(off) Yes or no Turns off pointer 
checking for pointers 
that follow 


8.1.4.5 Checking for Stack Overflow: the Stack Check Option 


Choose the Stack Check check box if you want QuickC to verify that your 
program has enough stack space at run time and to return a diagnostic 
message if it does not. 


Stack checking is performed by routines known as “stack probes.” A stack 
probe is called on entry to a function to verify that there is enough room 
in the program stack to allocate local variables required by the function. 
The stack probe is called at every function entry point. It generates a 
stack-overflow message if it finds that the required stack space is not 
available. Since stack checking can catch errors that otherwise might halt 
the operation of QuickC or DOS, the use of Stack Check during program 
development is strongly recommended. 


When stack checking is turned off, stack-probe routines are not called, 
and stack overflow may occur without being diagnosed (that is, no error 
message is displayed). However, programs that do not include the stack- 
checking code are smaller and faster than programs that do. 


Use the check_ stack pragma when you want to turn stack checking on or 
off for selected routines only, leaving the default (see below) for the 
remaining routines in the module. When you want to turn on stack check- 
ing, put the following line before the definition of the function that you 
want to check: 


# pragma check_ stack (on) 
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This line turns on stack checking for all routines that follow it in the 
source file, not just for the routines on the following line. To turn off stack 
checking, insert the following line: 


# pragma check_ stack (off) 


If no argument is given for the check_ stack pragma, stack checking 
reverts to the behavior specified by the Stack Check option line: turned on 
if the Stack Check option is turned on, or turned off otherwise. The 
interaction of the check_ stack pragma with the Stack Check option is 
explained in greater detail in Table 8.2. 


Table 8.2 
Using the check_ stack Pragma 


Compiled with 

Syntax Stack Check? Action 

# pragma check_ stack() Yes Turns on stack checking 
for routines that follow 

# pragma check_ stack() No Turns off stack checking 
for routines that follow 

# pragma check_stack(on) Yes or no Turns on stack checking 
for routines that follow 

# pragma check_ stack(off) | Yes or no Turns off stack checking 


for routines that follow 


It is a good practice to choose the Stack Check option unless you are sure 
that your program does not exceed the available stack space. For example, 
you may not need this option for programs that make very few function 
calls, that have only modest local variable requirements, or that do no 
recursion. 


8.1.4.6 Using Microsoft Extensions to C: 

the Language Extensions Option 
Choose the Language Extensions check box if you want to use the exten- 
sions to the ANSI C standard that are offered in the Microsoft QuickC 


Compiler. These extensions include the following: 


e The cdecl, far, fortran, near, and pascal keywords 
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e Use of casts to produce lvalues, as in the following example: 


int *p; 
((long *)p)++; 


e Use of the trailing comma (,) rather than a comma followed by 
ellipsis dots (,...) in function declarations to indicate variable- 
length argument lists, such as 


int printf(char +*,); 


e Benign typedef redefinitions within the same scope, as in the fol- 
lowing example: 


typedef int INT; 
typedef int INT; 


e Use of mixed character and string constants in an initializer, such 
as those in the code below: 


char arr[6] = {'a‘', 'b', "cde"}; 


e Use of bit fields with base types other than unsigned int or 
signed int 


Note 


The far keyword cannot be used to declare data items for in-memory 
programs, even if the Language Extensions option is selected. However, 
it can be used to declare pointers to data items. 


Do not choose the Language Extensions option if you will be compiling 
with compilers that do not recognize Microsoft’s extensions to the C 
language. Turning Language Extensions off causes extended keywords to 
be treated as simple identifiers and the other extensions listed above to be 
considered as illegal constructions. 


When language extensions are disabled, the compiler automatically defines 
the identifier NO. EXT_KEYS. In the include files provided with the 
run-time library, this identifier is used with # ifndef preprocessor direc- 
tives to control use of the cdecl keyword in library-function prototypes. 
For an example of this conditional compilation, see the include file named 
stdio.h. 
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8.1.4.7 Creating Faster Programs: 
the Optimizations Option 


Choose this check box to optimize your program for execution speed. The 
optimizations performed include constant folding, auto-enregistering, and 
automatic generation of 80286 instructions. 


Programs compiled with this option may be slightly larger than programs 
compiled without it, but they execute faster. 


8.1.4.8 Searching for Include Files: 
the Include Text Box 


If you want to search for include files in directories other than those given 
in the INCLUDE environment variable, type one or more search paths 
separated by commas (,) in the Include text box. The compiler searches the 
directory or directories you type, in the order you type them, before it 
searches the standard places given in the INCLUDE environment vari- 
able. The directories are searched in the order you give them. 


If QuickC cannot find an include file in the directories you type in the text 
box or in the directories given by the INCLUDE variable, the compiler 
displays an error message and stops processing. In this case, you must 
recompile the program and tell QuickC where to find the missing include 
file, using either the INCLUDE variable or the Include text box. 


8.1.4.9 Defining Constants and Macros: 
the Define Text Box 


Use the Define text box to define a constant or macro for your source file. 
Type one or more constant or macro definitions of the following form, 
separated by commas (,): 


identifier= string 


In each definition, z:dentzfier is the name of the constant or macro and 
string is its value or meaning. If you leave out both the equal sign and 
string, the given constant or macro is assumed to be defined, and its value 
is set to 1. For example, SET is sufficient to define a macro named SET 
with a value of 1. 


The Define option is especially useful if you use it with #if and # ifdef 
directives to perform conditional compilation of source files. 


If you give the equal sign with an empty string, the given constant or 


macro is considered defined, and its definition is the empty string. Such a 
definition effectively removes all occurrences of the identifier from the 
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source file. For example, to remove all occurrences of REGISTER, use the 
following option: 


REGISTER= 


Note that the identifier register is still considered to be defined, since 
case is significant in names. 


Typing macro and constant definitions in the Define text box has the same 
effect as using a # define preprocessor directive at the beginning of your 
source file or a /D option on the QCL command line. The identifier is 
defined in the source file being compiled until either an # undef directive 
removes the definition or the end of the file is reached. 


If an identifier defined in the Define text box is also defined within the 
source file, the definition given in the text box is used until the identifier is 
redefined in the source file. 


m Example 


#if !defined (RELEASE) 
—nheapchk (); — 
#endif 


This example calls a function to check the near heap unless the constant 
RELEASE is defined. While the program is under development, you can 
leave RELEASE undefined and perform heap checking to find bugs. Then, 
when you have found all of the bugs in the program, define RELEASE so 
that the program will run faster. 


8.1.4.10 Compile Command Buttons 


The command buttons on the Compile dialog box tell QuickC whether to 
compile the source file you are editing or the modules in the current pro- 
gram list. Select any of the following command buttons: 


Command Button Use 


Build Program Recompiles all modules in the current pro- 
gram list that have been changed since the 
last time you rebuilt the program, then 
rebuilds the program. See Section 6.1.4 for a 
detailed description of this procedure. The 
resulting object files, linker-response file, exe- 
cutable file, and (if the Debug option is 
turned on) map file are saved on disk. If no 
program list is present, compiles the source 
file you are currently editing. 


173 


Microsoft QuickC Compiler Programmer’s Guide 


Compile File 


Rebuild All 


Cancel 


Compiles the source file you are currently 
editing. 


Recompiles all modules in the current pro- 
gram list, whether or not they have been 
changed since the last time you rebuilt the 
program, then rebuilds the program. See Sec- 
tion 6.1.4 for a detailed description of this 
procedure. The resulting object files, linker- 
response file, executable file, and (if the Debug 
option is turned on) map file are saved on 
disk. If no program list is present, compiles 
the source file you are currently editing. 


Cancels compilation and returns you to the 
view window. 


8.1.5 Controlling Run-Time Options: 
the Set Runtime Options... Command 


The Set Runtime Options... command controls various aspects of a pro- 
gram’s behavior at run time. These options go into effect the next time the 
program is started or restarted. 


When you select Set Runtime Options... from the File menu the dialog 
box shown in Figure 8.3 opens. 


Name of current program list 


Options for next invocation of Lexer 
Command Line: 


Memory Requirements: 


Near Data: |65535 


Type the number of bytes 
in the default data segment. 


Command-line arguments 
for the program 


Type the number of bytes 
in the stack. 


Figure 8.3 The Set Runtime Options ... Dialog Box 
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The following list describes the options in the Set Runtime Options... dia- 


log box: 
‘Option 


Comuand Line 


Near Data 


Stack 


Use 


Type the arguments you would type after the © 
program name if you ran the program from 
the DOS command level. These arguments 

are passed to the program through the stan- 
dard argu and argc arguments to the C main 
function. 


To reduce the amount of memory allocated 
for the default data segment (64K by default), 
type the number of bytes, in decimal, to be 
allocated. The default data segment contains 
all initialized global and static program data 
except data explicitly declared with the far 
keyword. You may want to reduce the size of 
this segment if your program does not use 
much data that would go in the default seg- 
ment, but does use a large amount of data 
(for example, large arrays) that would be allo- 
cated in other data segments. See Appendix 
B, “Working with QuickC Memory Models,” 
for more information about allocation of 
data. See Appendix C, “Interfacing C with 
Assembly Language,” for more information 
about the default data segment and the other 
segments used by the Microsoft QuickC Com- 
piler. 


To use a stack size other than the default 
(2K), type the number of bytes, in decimal, in 
the Stack text box. The largest stack size you 
can request is 64K. You may want to increase 
the stack size if your program gets stack- 
overflow diagnostic messages. Conversely, if 
your program uses the stack very little, you 
may want to decrease the size of your pro- 
gram by reducing the stack size. 
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8.2 Debugging Programs 


The Microsoft QuickC Compiler contains powerful debugging features 
that make it easy to isolate errors in program logic. For example, use the 
debugger to trace and single-step program execution, set breakpoints, and 
examine the values of variables and expressions. 


8.2.1 General Debugging Procedure 


Use the following general procedure to debug a program within the 
QuickO programming environment: 


1. Compile the program with the Debug option in the Compile dialog 
box turned on. 


2. Turn on any debugging features such as breakpoints, watch expres- 
sions, or screen swapping by using the keyboard or Debug menu 
commands described in Section 8.2.3. 


3. Run your program by using the keyboard commands described in 
Section 8.2.2 or the Start, Restart, and Continue commands on the 
Run menu. Observe the order in which statements and functions 
are executed, the changes made to watch variables, and the pro- 
gram output. 


4. Edit your program as needed to correct errors you found in step 3. 
Then recompile your program, again choosing the Debug option 
from the Compile menu. 


5. If you need to change any of the debugging information, go back to 
step 2. Otherwise, go back to step 3 and rerun your program. 


6. Repeat steps 3-5 until your program runs correctly. 


8.2.1.1 Adding Watch Expressions 


When you add a watch expression, QuickC opens a window, known as a 
“watch window,” at the top of the screen and displays the values of watch 
expressions in the window. During program execution, QuickC continu- 
ously displays the values of watch expressions, changing them at each 
point in the program where the corresponding program variables change. 
Unexpected changes in the value of a watch expression may indicate pro- 
gram errors. 


Select the Add Watch command from the Debug menu to add a watch 
expression. Use the Delete Last Watch command from the Debug menu, or 
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type SHIFT+F2, to delete the last-added watch expression. Use these com- 
mands together to view the values of local variables while tracing through 
the functions in which these variables are defined, then delete the watch 
expressions for these variables after exiting the function. 


Select the Delete All Watch command from the Debug menu to delete all 
watch expressions. 


8.2.1.2 Setting Breakpoints 


“Breakpoints” are set at particular lines in the program. Setting a break- 
point tells QuickC to stop program execution temporarily at that line in 
the program. Breakpoints are often used in conjunction with watch expres- 
sions: set breakpoints at lines in the program where you suspect bugs, then 
check the watch expressions at these points for unexpected values. 


To toggle a breakpoint on or off, move the cursor to the line where you 
want to toggle the breakpoint. Then either press F9 or select the Toggle 
Breakpoint command from the Debug menu. To delete all breakpoints, 
select the Clear All Breakpoints command from the Debug menu. (See Sec- 
tion 8.2.3.5, “Controlling Breakpoints,” for more information on the Clear 
All Breakpoints command.) 


8.2.2 Debugging Keyboard Commands 


QuickC provides the following single-keystroke debugging commands: 


Command To: Key 
Execute the next program F8 


statement; trace through function 


Execute the next program F10 
statement; trace around function 


Execute the program to the current F7 
cursor position 


Display the output screen F4 


To execute the program to the line where the mouse pointer is pointing, 
click that line with the right-hand mouse button. 


8.2.3 Debugging Commands: the Debug Menu 
Figure 8.4 shows the Debug menu. 


177 


Microsoft QuickC Compiler Programmer’s Guide 


Add Watch.. 
Delete Last Watch Shift+FZ 
Delete All Watch 


Trace On 


Jf Screen Swapping On 


Toggle Breakpoint 
Clear All Breakpoints 


Figure 8.4 The Debug Menu 


The commands in the Debug menu perform the following actions: 


Command 


Add Watch... 


Delete Last Watch 


Delete All Watch 


Trace On 
Screen Swapping On 
Toggle Break point 


Clear All 
Breakpoints 


Action 
Adds one or more new watch expressions to 
the watch window. 


Deletes the most recently added watch expres- 
sion from the watch window. The shortcut 
key sequence for this command is SHIFT+F2. 


Deletes all watch variables from the watch 
window. 


Toggles program tracing on or off. 
Toggles screen swapping on or off. 


Turns a breakpoint on or off on the line where 
the cursor is resting. The shortcut key for this 
command is F9. 


Clears all breakpoints from the current pro- 
gram. 


Sections 8.2.3.1-8.2.3.5 describe the commands on the Debug menu. 


8.2.3.1 Adding Watch Expressions: 
the Add Watch... Command 


Use the Add Watch... command to add one.or more watch variables to the 
watch window at the top of the view window. 


When you choose Add Watch... from the Debug menu, the dialog box 


shown in Figure 8.5 opens. 
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Enter expression to add to Watch Window 


Figure 8.5 The Add Watch... Dialog Box 


Type one or more watch expressions in the text box. If you type more than 
one expression, type a semicolon at the end of each expression. 


A watch expression may be any of the following: 


e A variable 


e A Cexpression consisting of variables combined with parentheses 
(( )), brackets ([]), the structure-member operator (.), the 
structure-pointer operator (->), or the indirection operator (*) 


e Anentire structure or array 
Note that math operators are not allowed in watch expressions. 


To display the value of a watch variable using a different output format, 
type a comma, followed by a format character, after the watch-variable 
name. Table 8.3 lists these format characters, along with examples of out- 
put that would appear for sample values stored in memory. 


Table 8.3 
Format Specifiers for Watch Variables 


* Output Watch Displayed 
Character Format Value Value 
d Signed decimal integer 40000 40000 
i Signed decimal integer 40000 40000 
u Unsigned decimal integer 40000 40000 
o Unsigned octal integer 40000 116100 


179 


Microsoft QuickC Compiler Programmer’s Guide 


Table 8.3 (continued) 


Output Watch Displayed 
Character Format Value Value 
x Hexadecimal integer 40000 9c40 
f Signed value in S725 1.500000 


floating-point 
decimal format 
with six decimal 
places 


e Signed value in 3272; 1.500000e+000 
scientific-notation 
format with up to 
six decimal places 
trailing zeros and 
ecimal point are 
truncated) 


g Signed value with 3./2. 1.5 
floating-point 
decimal format (f) 
or scientific- 
notation format (e), 
whichever is more 


compact 
Single character 65 A 
Characters printed "String" String 


up to the first null 


character 


If no format specifier is given, the QuickC debugger uses the default for- 
mat specifier for the type of the watch variable. For structures, each field 
is displayed with the default format specifier for the field type. Single- and 
ae hc real numbers are displayed by using the g format spe- 
cifier. 


The prefix h can be used with the integer format specifiers (d, 0, u, and x) 
to specify a two-byte integer. The prefix 1 can be used with the same types 
to specify a four-byte integer. For example, if the value of a watch vari- 
able is 100,000, the 1d specifier produces the output 100000. However, 
the hd specifier evaluates only the low-order two bytes, producing the 
output -31072. 


Format specifiers for watch variables work the same way as format speci- 
fiers for the printf families of library functions. As a result, specifying a 
watch variable of one type and a format specifier of a different type does 
not implicitly cast the watch variable to the type of the format specifier. 
Instead, the bit pattern at the memory location represented by the watch 
variable appears as if it represented an item of the same type as the for- 
mat specifier. For example, if a variable of type int has the value 4, and if 
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you display it with the f format specifier, the displayed value will be 
“0.00000” rather than “4.00000.” This value is displayed because, in 
floating-point format, the bit pattern “00000100” format represents a 
number with such a small exponent that the number is effectively 0. 


You are not restricted to viewing the contents of a watch variable. If you 
type more than one format character after a watch-variable name, each 
format character represents a memory location after the location of the 
watch variable. The QuickC debugger displays the value stored at each of 
these memory locations, using the format given by the format character. 


After you type the watch expressions in the text box, choose the OK com- 
mand button to add these expressions to a watch window or the Cancel 
command button to cancel the Add Watch... command. 


Note that a watch expression is undefined if it is not defined for the func- 
tion currently being executed (that is, if it is out of scope). 


@ Examples 


watchvar, f 


The example above displays the value of the watch variable watchvar in 
floating-point decimal format with six decimal places. 


watchvar,dulxl10c 


This second example displays the value of the watch variable watchvar 
in signed-decimal format. The values of the twelve memory locations fol- 
lowing the address of watchvar are also displayed, in the formats shown 
below: 


e An unsigned decimal number 


e A long hexadecimal number 


e Ten characters 


8.2.3.2 Deleting Watch Variables: the Delete Last 
Watch/All Watch Commands 


The Delete Last Watch command deletes the most recently added watch 
expression from the watch window. If you added more than one watch 
expression with a single Add Watch... command, only the last expression 
given in the text box is deleted. The shortcut key sequence for this com- 
mand is SHIFT+F2. 


181 


Microsoft QuickC Compiler Programmer’s Guide 


The Delete All Watch command deletes all watch expressions and closes 
the watch window. 


8.2.3.3. Controlling Tracing: the Trace On Command 


The Trace On command toggles program tracing on or off. A check ap- 
pears next to this command on the Debug menu when tracing is turned on. 


If you choose the Start or Continue command from the Run menu when 
tracing is turned on, the program executes up to the next breakpoint, 
highlighting each currently executing statement. If the next execut- 

ing statement is in another module, that module is displayed in the view 
window. 


When tracing is turned off, the currently executing statement is not 
highlighted. Execution proceeds immediately to the first breakpoint, which 
is the first statement that is highlighted. 


8.2.3.4 Controlling Screen Swapping: 
the Screen Swapping On Command 


The Screen Swapping On command toggles screen swapping on or off. A 
check appears next to this command on the Debug menu when screen 
swapping is turned on. 


If screen swapping is on, the QuickC screen disappears and is replaced by 
the program-output screen at each step of program execution; conse- 
quently, flickering is constant. 


If screen swapping is off, the output screen appears only if the program 
performs an output operation using an output or graphics function. This 
removes the flickering effect that results from having screen swapping on. 


8.2.3.5 Controlling Breakpoints: the Toggle Breakpoint 
and Clear All Breakpoints Commands 


The Toggle Breakpoint and Clear All Breakpoints commands control the 
use of breakpoints during debugging. 


The Toggle Breakpoint command turns a breakpoint on or off on the line 
where the cursor is resting. If a breakpoint is currently set, the command 
turns the breakpoint off; if a breakpoint is not set, the command sets one. 
The shortcut key for this command is F9. 
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Lines where breakpoints are set have the colors and other attributes given 
by the Breakpoint Lines option in the Options... dialog box from the View 
menu. 


The Clear All Breakpoints command removes all breakpoints from the 
program being debugged. 


8.2.4 Tracing Between Functions: 
the Calls Menu 


Selecting the Calls menu displays a list of the functions that have been 
called. You can use the list to display a function. You can also use the list 
to execute a program up to a particular function. 


For example, selecting the Calls menu while the CELOW.C program is run- 
ning might produce the display shown in Figure 8.6. 


makename( ‘’readtoken"’ > 
findproct ) 
main(1, @xZaas> 


Figure 8.6 The Calls List Display 


When the Calls list is displayed, you can use the mouse or the DIRECTION 
keys and the ENTER key to select one of the functions. QuickC displays the 
function and places the cursor on the next statement that will be executed 
when control returns to the calling function. 


If you have accidentally traced into a function and want to get out of that 
function immediately, follow these steps: 


1. Open the Calls menu. 


2. Use the UP and DOWN keys to highlight the name of the function 
from which you called the function you are tracing through, and 
press ENTER. 


3. Press F7. 


The QuickC debugger returns you to the point immediately after the point 
from which you called the function. 
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The Microsoft QuickC Compiler is not just an 
integrated programming environment; it also 
includes several powerful programming tools 
that complement the integrated environment. 
This section shows how to use these tools, which 
include 


e The QCL compiler driver, which creates 
object and executable files on disk from C 
source files 

e ‘The LINK overlay linker, which combines 
object files and stand-alone libraries into 
executable files or Quick libraries 

e ‘The LIB library manager, which combines 
object files into stand-alone libraries 

e The MAKE program-maintenance utility, 
which automatically updates programs 
whenever a program module is updated 
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Once you have mastered the QuickC programming environment, you can 
gain extra control over how programs will work by compiling and linking 
them outside the environment. You might want to do this for any of the 


following reasons: 


e To create source programs using your own editor 


e Tocompile programs that cannot be compiled within the QuickC 
programming environment 


e To use different memory models in the programs that you create 


e To change the default naming or function-calling conventions for 


your programs 


e To generate specialized instructions for an 80286 processor when 
you compile your program 


e To create listings showing output from the C preprocessor or show- 
ing program segments, in order of appearance 


The Microsoft QuickC Compiler includes a program named QCL that can 
compile and link programs outside of the QuickC environment. The fol- 
lowing chapter shows how to use QCL and the Microsoft Overlay Linker, 
LINK. It is organized as shown below: 


Sections 


9.1-9.1.2 


9.2-9.3 


9.49.7 


Contents 


Describe the compiling and linking process. Read 
this section if you are new to Microsoft language 
products; otherwise, turn to Section 9.2. 


Explain how to compile and link programs using a 
single QCL command line and describe files and 
options you can give as input to the QCL com- 
mand. 


Explain how to compile and link in two steps: by 
compiling with QCL, then linking with LINK. 
These sections describe information that QCL 
passes to LINK and list files and options you can 
give as input to the LINK command. 


9.1 The Compiling and Linking Process 


The following procedure is used to create a stand-alone program from a C 
source file outside of the QuickC programming environment: 


1. Each source file in the program is compiled, creating an object file. 


191 


Microsoft QuickC Compiler Programmer’s Guide 


2. The object files are linked with one or more stand-alone libraries 
(libraries with .LIB extensions) to form an executable file. The 
linker resolves external references in the object files before it cre- 
ates the executable file. (That is, it makes sure that all function 
calls in the object files match up with functions in the hbraries or 
with functions in other object files.) 


Sections 9.1.1 and 9.1.2 describe two methods that you can use to compile 
and link programs. Figure 9.1 illustrates these methods. 


QCL/options 


— automatically 
calls linker 


LINK/options 


Figure 9.1 Compiling and Linking Programs 
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9.1.1 Using a Single QCL Command Line 


You can compile and link programs using a single QCL command line. 
Specifically, the same command line can be used to specify source files to 
be compiled, object files and libraries to be linked, and options that con- 
trol the compiler and linker. QCL compiles any source files you specify, 
then passes any object-file names, library names, and linker options to the 
linker, which then links the object files and libraries to produce an execut- 


able file. : 


9.1.2 Using the QCL and LINK Commands 


As an alternative, you can compile first with QCL and the /c option, then 
use the LINK command to invoke the linker explicitly. The advantage of 
using this method is that you do not need to use a single command line to 
give the linker all the information it needs; the LINK command prompts 
you for any information that you do not give. See Sections 9.4.2.1—9.4.2.4 
for instructions for using the LINK command. 


9.2 One-Step Compiling and Linking: 
the QCL Command 


To compile and link with the QCL command, your DOS environment 
should be set up as summarized below. For a full description, see Section 
1.3.1.6 (for hard-disk users) or Section 1.3.2.4 (for floppy-disk users). 


e If you are using a hard-disk system, use the DOS CD command to 
make the directory with your source file the current directory. 


e If you are using a floppy-disk system, insert the disk containing 
your source program in drive B and your copy of the Product dis- 
tribution disk in drive A. Make drive B the current drive. When 
you run QCL, type the drive name A: immediately before the 
QCL command, with no intervening spaces. During the 
compiling/linking process, you will be prompted to swap in drive A 
your working copy of the Work distribution disk and the disk con- 
taining the appropriate stand-alone library. 


The QCL command has the following format: 
QCL [option]... file... [option| file]... [/link [l7b... link-opt...]]| 
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The information you enter on the QCL command line is explained in the 
following list: 


Entry Meaning 


option A QCL option; see Sections 9.3.1—9.3.13 for 
descriptions. For a quick overview of the com- 
monly used options, type 


QCL /HELP 
and press ENTER. 


file The name of a source or object file that you want 
to process, or the name of a library that you want 
to pass to the linker for processing. You must give 
at least one file name. See Sections 9.2.1.1—9.2.1.3 
for information about specifying file names to the 


QCL command. 


lib The name of a stand-alone library that you want 
to pass to the linker for processing. See Section 
9.4.2.3 for more information about specifying 
stand-alone libraries. 


link-opt One or more of the linker options described in Sec- 
tions 9.5.1-9.5.14; the QCL command passes these 
options to the linker for processing. Ordinarily, 
you do not need to give linker options unless you 
want the linker to perform a special operation such 
as linking with a specified library, changing the 
program stack size, creating a map file, or includ- 
ing debugging information in the executable file. 


You can give any number of options, file names, and stand-alone-library 
names on the QCL command line, as long as the command line does not 
exceed 128 characters. 

9.2.1 Specifying File Names 

The QCL command makes certain assumptions about the files you 
specify, based on the path names and extensions you use for the files. The 
following sections describe these assumptions and other rules you should 
follow in specifying file names to QCL. 


9.2.1.1 Uppercase and Lowercase Letters 


You can use any combination of uppercase and lowercase letters for file 
names, just as in DOS. (Note that QCL options are case sensitive.) 
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9.2.1.2 File-Name Extensions 


A DOS file name has two parts: the “base name,” which includes every- 
thing before the period (.); and the “extension,” which includes the period 
and up to three characters following the period. The extension identifies 
the type of the file. 


The QCL command uses the extension of each file name to determine how 
to process the corresponding file, as explained in the following list: 


Extension Processing 
.C QCL assumes the file is a C source file and com- 
piles it 
-OBJ QCL assumes the file is an object file and passes it 
to the linker for linking 
-.LIB QCL assumes the file is a stand-alone library and 


passes it to the linker for linking with the gen- 
erated object files and the object files given on the 
command line 


Any other QCL assumes the file is an object file and passes it 
extension or no to the linker for linking 
extension 


m Example 

The command line 

OC: AsC. BwC:- C.OBI-D 

compiles the files A.C and B.C, creating object files named A.OBJ and 
B.OBJ. These object files are then linked with C.OBJ and D.OBJ to 
form an executable file named A.EXE (since the base name of the first file 
on the command line is A). Note that the extension .OBJ is assumed for 
D since no extension is given on the command line. 

9.2.1.3 Path Names 

Any file name can include a full or partial path name. A full path name 


starts with the drive name; a partial path name has one or more directory 
names before the file name, but does not include a drive name. 
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Giving a path name allows you to specify files in different paths as input to 
QCL and allows you to create files on different drives or in different direc- 
tories on the current drive. 


For output files (such as object or executable files) that you create with 
QCL, you can give a path name ending in a backslash (\) to create the 
file in that path. When it creates the file, QCL uses the default name for 
the file. 


If you do not give a full or partial path name, QCL assumes that the 
source and object files you specify are in the current working directory, 
where it creates all output files. 


9.3 Controlling Compilation 
with QCL Options 


Options to the QCL command consist of either a forward slash (/) ora 
dash (—) followed by one or more letters. (In this manual, forward slashes 
are used for options, although in error messages dashes are used.) 


Important 


QCL options are case sensitive. For example, /W and /w are two 
different options. 


Options can appear anywhere on the QCL command line. Unless other- 
wise stated, a QCL option applies to the files that follow it on the com- 
mand line and does not affect files preceding it on the command line. 
All QCL options are compatible with the Microsoft C Optimizing Com- 
piler, Version 5.0. 


=m Common Options in the CL Environment Variable 


If you are recompiling a given set of files more than once, or if you use the 
same set of options when you compile, the CL environment variable can 
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save you from having to retype the files and options on the command line 
each time you recompile. Use the DOS SET command as shown below to 
define the value of CL: 


SET CL= [[option|file]... [/link[link-libinfo}]]] 


This variable is also useful if you usually give a large number of files and 
options when you compile: since the files and options that you define with 
this variable are not counted in the 128-character limit for the command 
line, you can define the files and options you use most often with the CL 
variable and then give on the command line only the files and options you 
need for specific purposes. 


The information you define with CL is treated as if it appeared before the 
information you give on the QCL command line. For example, if you use a 
command sequence of the form 


SET CL=/Fm TEST1.C /link LIB1.LIB /PAC 
QCL /Zi TEST2.C /link LIB2.LIB /STOxCOO 
the effect would be the same as entering 


QCL /Fm TEST1.C /Zi TEST2.C /link LIB1.LIB /PAC 
LIB2.LIB /STOxCOoOo 


Note that if you have defined a file or option with CL, you generally can- 
not turn off the definition from the command line. You must reset the 

CL environment variable and omit the file or option that you do not want 
to use. 


Since options defined in the environment are treated as if they appeared 
before options given on the command line, they affect any files given on 
the command line. However, you can override the effect of an option de- 
fined in the environment by explicitly giving a different option on the com- 
mand line. In cases where one option is defined in the environment and a 
conflicting option is given on the command line, the command-line option 
takes precedence for any files that follow it on the command line. 


= QCL Options and Object Files 


Most QCL options apply only to the compilation process and do not affect 
object files given on the command line. See Table 9.2 in Section 9.3.2 for a 
list of the QCL options that affect the linking process. 
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m= Examples 


SET CL=FILE1.C FILE2.C 
QCL FILE3.OBJ 


In the example above, the CL environment variable tells the QCL com- 
mand to compile and link the source files FILE1.C and FILE2.C. The 
QCL command 


QCL FILE1.C FILE2.C FILE3.OBJ 


would then have the same effect as the first command line. 


SET CL=/Za 


QCL FILE1.C /Ze FILE2.C 


The example above illustrates how to turn off the effects of a CL option 
defined in the environment. In this example, the CL environment variable 
is set to the /Za option, described in Section 9.3.1, which tells the com- 
piler not to recognize Microsoft extensions to the C language. This option 
causes Microsoft-specific keywords to be treated as ordinary identifiers 
rather than reserved words. The CL command specifies the inverse option, 
/Ze, which tells the compiler to treat language extensions as reserved 
words. Since the effect is the same as compiling with the command line 


QCL /Za FILE1.C /Ze FILE2.C 


FILE1.C is compiled with language extensions turned off and FILE2.C 
is compiled with language extensions enabled. 


9.3.1 Environment Options 


A number of QCL options have the same effects as options in the Compile 
dialog box. Table 9.1 shows these QCL options, the corresponding Com- 
pile options and the sections where these options are discussed, and the 
effect of each QCL option. 
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QCL Options and Compile Dialog Box Options 


QCL Option 
/c 
/D identifier|= [string] 


/Gs 


/Mdirectory 
/Ot 


/Ox 


/W{{0|1|2/3} | 


/Za 


Compile Option 
Obj button on 


Define text box 
(8.1.4.9) 


Stack Check check 
box off (8.1.4.5) 


Include text box 
(8.1.4.8) 


Optimizations check 
box on (8.1.4.7) 


Optimizations check 
box on (8.1.4.7) and 
Stack Check check 
box off (8.1.4.5) 


Warning Level 
button on (8.1.4.1) 


Language 
Extensions check 
box off (8.1.4.6) 


Effect 


Creates an object file 


on disk 


Defines symbolic 
constants or macros. 
The /D option 
allows up to 16 
definitions if 
language extensions 
are turned off (/Za 
compiler option or 
Language Extensions 
circular button in 
the environment) or 
up to 17 definitions 
if they are enabled. 


Disables stack probes 


Tells the compiler 
which paths to 
search for include 
files. Each /I option 
specifies a different 
directory. 


Optimizations favor 
execution time over 
code size. 


Performs maximum 
optimization of 
programs. This 
option also turns on 
loop optimizations; 
see Section 9.3.13 for 
more information 
about loop 
optimizations. 


Sets the warning 
level for warning 
messages 


Disables Microsoft 
extensions to the 


ANSI C standard 
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Table 9.1 (continued) 


QCL Option 


/Za 


/Zq 
/Zr 


/Zs 


create an object file 


Compile Option 


Debug check box on 
(8.1.4.3) 


Debug check box on 
(8.1.4.3) 


Debug check box on 
(8.1.4.3) | 
Pointer Check check 


box on (8.1.4.4) 


Syntax Check Only 
button on (8.1.4.2) 


Effect 


Produces an object 
file containing line- 
number records 
corresponding to the 
line numbers of the 
source file. Useful 
when you want to 
pass an object file to 
the SYMDEB 
symbolic debugger. 
This debugger can 
use the line numbers 
to refer to program 
locations; however, 
it cannot refer to 
local symbols in 
your programs. 


Puts information 
needed for 
debugging in object 
file; allows file to be 
used with QuickC 
debugging or 
Microsoft CodeView 
symbolic debugger. 
To use the program 
with QuickC 
debugging, the /Zi 
option must be given 
with the /Zd and 
/Zq options. 


Generates interrupts 
needed for QuickC 
debugging. 

Checks for null 
pointers or out-of- 
range far pointers 


Checks program 
syntax only; does not 


See Section 8.1.4 for more information about the effects of these options. 
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9.3.2 Options to Control Linking 


Several QCL options affect the linking process rather than the compila- 
tion process. These options have the same effects as prompts, command- _ 
line fields, or options of the LINK command. Table 9.2 shows these QCL 
options, the corresponding LINK features, and their effects. 


Table 9.2 
QCL and LINK Options 


QCL LINK 
Option Option Effect 
/F hernum /STACK:number Sets the program 
stack size (see 
Section 9.5.11) 
/Felezefile] Run File prompt Names the 
or ezefile field executable file 
(see Section 
9.4.2.2) 
/Fm|mapfile] List File prompt, Creates a map 
mapfile field, or file showing 
/MAP option program 
segments, in 
order (see 


Section 9.5.10). 
The /Fm option 
allows you to 
rename the map 
file, if desired. 


9.3.3 Listing the Compiler Options (/HELP) 


= Option 


/HELP 
/help 


This option displays a list of the most commonly used compiler options. 
QCL processes all information on the line containing the /help option, 
and displays the command list. 


This option is not case sensitive: any combination of uppercase and lower- 


case letters is acceptable. For example, /hELp is a valid form of this 
option. 
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9.3.4 Naming the Object File (/Fo) 


= Option 
/Foobyfile 


The /Fo option gives different names to object files or, if you specify a 
path name, creates them in a different directory. 


Keep the following rules in mind when using this option: 


e The objfile argument must appear immediately after the option, 
- with no intervening spaces. 


e Each /Fo option applies to the next source file that appears on the 
command line after the option. 


You are free to supply any name and any extension you like for objfile. 
However, it is recommended that you use the conventional .OBJ extension 
because the linker and the LIB library manager use .OBJ as the default 
extension when processing object files. 


If you do not give a complete object-file name with the /Fo option (that 
is, if you do not give an object-file name with a base and extension or if 
you give a path name with no file name), QCL names the object files 
according to the following rules: 


e If you give an object-file name without an extension (such as 
TEST), QCL automatically appends the .OBJ extension. 


e If you give an object-file name with a blank extension (such as 
TEST. ), QCL leaves the extension blank. 


e If you give a path name with no file name, QCL creates the object 
file in the directory with the given path and gives it the base name 
of the first source file on the command line plus the .OBJ exten- 
sion. In this case, the path name must end with a backslash (\) so 
that QCL does not mistake the path name for a file name. 


m Examples 

QCL /FoB:\OBJECT\, FILE1.C 

In the example above, the source file FILE1.C is compiled; the resulting 
object file is named FILE1.OBJ (by default). The directory specification 


B:\OBJECT\ tells QCL to create FILE1.OBJ in the directory named 
\OBJECT on drive B. 
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QCL /Fo\OBJECT\ FILE1.C FILE2.C /Fo\SRC\NEWFILE3.OBJ FILE3.C 


In the example above, the first /Fo option tells the compiler to create, in 
the \OBJECT directory, the object files FILE1.OBJ (created as a result 
of compiling FILE1.C) and FILE2.OBJ (created as a result of compiling 
FILE2.C). The second /Fo option tells the compiler to create the object 
file named NEWFILE3.OBJ (created as a result of compiling FILE3.C) 
in the \SRC directory. 


9.3.5 Memory-Model ( ey) and 
Floating-Point (/FP) Options 


Two important options that you specify with the QCL command are the 
following: 

1. The memory model used for your program 

2. The way your program handles floating-point-math operations. 
The memory model defines the rules that the compiler will use to set 


up the program’s code and data segments in memory. QCL offers the 
memory-model options described in Table 9.3. 


Table 9.3 
Memory Models 
CL Memory Data Code 
Option Model Segments Segments 
/AS Small One One 
/AM Medium One One code 
segment for 
each 
module 
/AC Compact Multiple One 
data 
segments; 
data items 
must be 
smaller 
than 64K 
/AL Large Multiple One code 
data segment per 
segments; module 
data items 
must be 
smaller 
than 64K 


203 


Microsoft QuickC Compiler Programmer’s Guide 


Generally, memory models with multiple code segments can accommodate 
larger programs than can memory models with one code segment, and 
memory models with multiple data segments can accommodate more 
data-intensive programs than can memory models with one data segment. 
However, programs with multiple code or data segments are usually slower 
than programs with a single code or data segment. 


By default, the Microsoft QuickC Compiler uses the medium memory 
model for programs compiled within the QuickC environment and the 
small memory model for programs compiled with the QCL command. (For 
more information about using and adjusting memory models, see Appen- 
dix B, “Working with QuickC Memory Models.” ) 


The QCL command includes the following options that allow you to 
choose how the program you are compiling will handle floating-point-math 
operations: 


Option Effect 
/FPi Handles floating-point-math operations with soft- 


ware that emulates the functionality of an 8087 or 
80287 math coprocessor. A coprocessor is not re- 
quired to run programs compiled with this option, 
although these programs run successfully on sys- 
tems with coprocessors. This option is the default. 


/¥ Pi87 Handles floating-point-math operations by gen- 
erating instructions for an 8087 or 80287 math 
coprocessor. This option reduces the size of pro- 
grams that will always be run on systems with a 
coprocessor. 


The floating-point and memory-model options you choose determine the 
name of the stand-alone library that QCL places in the object file it 
creates. If you plan to link with that library, you do not need to give the 
linker a library name. Table 9.4 shows each combination of memory-model 
and floating-point options and the corresponding library name that QCL 
embeds in the object file. 
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Table 9.4 
QCL Options and Default Libraries 


Floating-Point | Memory-Model Default 


Option Option Library 

/¥F Pi87 /AS SLIBC7.LIB 
/AM MLIBOC7.LIB 
/AC CLIBC7.LIB 
/AL LLIBC7.LIB 

/FPi /AS SLIBCE.LIB 
/AM MLIBCE.LIB 
/AC CLIBCE.LIB 
/AL LLIBCE.LIB 


9.3.6 Using the 8086 or 80286 Processor 
(/GO, /G2) 


= Options 


/GO Enables instruction set for 8086/8088 processor (default) 
/G2_ Enables instruction set for 80286 processor 


If you have an 80286 processor, you can use the /G2 option to enable the 
80286 instruction set for your program. By default, the Microsoft QuickC 
Compiler uses the 8086/8088 instruction set. Although it is usually advan- 
tageous to compile with /G2 if your machine has an 80286 processor, you 
are not required to do so. Programs compiled with the /G2 option cannot 
run on a machine with an 8088 or 8086 processor. However, programs 
compiled without the /G2 option and programs explicitly compiled with 
the /GO option can run on a machine with an 80286 processor. 


9.3.7 Controlling the Preprocessor 


The QCL command provides several options that control the operation of 
the C preprocessor. You can define macros and manifest (symbolic) con- 
stants from the command line, change the search path for include files, 
and stop compilation of a source file after the preprocessing stage to pro- 
duce a preprocessed source-file listing. 
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9.3.7.1 Removing Definitions of 
Predefined Identifiers (/U, /u) 


= Options 


/U identifier Removes definition of a predefined identifier 
/u Removes definitions of all predefined identifiers 


The Microsoft QuickC Compiler defines four identifiers that are useful in 
writing portable programs. Use these identifiers to conditionally compile 
parts of a program, depending on the processor, operating system, and 
memory model being used. The predefined identifiers and their functions 
are listed below: 


Identifier Function 

MSDOS Always defined. Identifies target operating 
system as DOS. 

M_ 186 Always defined. Identifies target machine as a 
member of the 8086 family. 

M_ I86mM Always defined. Identifies memory model, 


where m is either S (small model), C (compact 
model), M (medium model), or L (large 
model). Memory models are discussed in 
Appendix B, “Working with QuickC Memory 
Models.” 


‘NO_EXT_ KEYS Defined only when language extensions are 
turned off (that is, when the program is com- 
piled with the Language Extensions circular 
button off or with the /Za compiler option). 


The /U (for “undefine”) option turns off the definition of the given 
predefined identifiers. One or more spaces may separate the /U and 
identifier. You can specify more than one /U option on the same command 
line. 


The /u option turns off all four definitions. 


You may want to remove definitions of predefined identifiers in the follow- 
ing cases: 


e If you want to give more than the maximum number of definitions 


on the command line. You can give 16 definitions if language 
extensions are turned off or 17 otherwise. 
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e If you want to use a predefined identifier to represent something 
different in your program. 


For each definition of a predefined identifier you remove, you can substi- 
tute a definition of your own on the command line. If you remove the 
definitions of all four predefined identifiers, you can specify up to 20 
command-line definitions. However, because DOS limits the number of 
characters you can type on a command line, the number of definitions you 
can specify in practice is probably less than 20. 


= Example 

QCL /UMSDOS /UM_I86 WORK.C 

This example removes the definitions of two predefined identifiers. Note 
that the /U option must be given twice to do this. 


9.3.7.2 Producing a Preprocessed Listing (/P, /E, /EP) 


= Options 


/P _ Writes preprocessed output to a file 
/E Writes preprocessed output to standard output; includes # line directives 
/EP Writes preprocessed output to a file and standard output 


The /P, /E, and /EP options produce listings of preprocessed files. These 
options allow you to examine the output of the C preprocessor. All three 
options suppress compilation; no object file or map file is produced, even if 
you specify an /Fo or /Fm option on the QCL command line. 


A preprocessed listing file is identical to the original source file except that 
all preprocessor directives are carried out, macro expansions are per- 
formed, and comments are removed. . 


The following list explains how each option handles preprocessed output: 


Option Output Handling 

/P Writes the preprocessed listing to a file with the 
same base name as the source file, but with an .I 
extension. 
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/E Copies the preprocessed listing to the standard 
output (usually your terminal); DOS redirection 
can be used to save the listing in a disk file. This 
option also places a # line directive at the begin- 
ning and end of each included file and around lines 
removed by preprocessor directives that specify 
conditional compilation. This option is useful when 
you want to resubmit the preprocessed listing for 
compilation. The # line directives renumber the 
lines of the preprocessed file so that errors gen- 
erated during later stages of processing refer to 
the original source file rather than to the prepro- 
cessed file. 


/EP Combines features of the /E and /P options: 
preprocesses the file and copies it to the standard 
output, but does not add # line directives. 

m Examples 

QCL /P MAIN.C 

This example creates the preprocessed file MAIN.I from the source file 
MAIN .C. 

QCL /E ADD.C > PREADD.C 

The command above creates a preprocessed file with inserted # line direc- 
tives from the source file ADD.C. The output is redirected to the file 
PREADD.C. 

QCL /EP ADD.C 

The command above produces the same preprocessed output as the second 


example, but without the #line directives. The output appears on the 
screen. 


9.3.7.3 Preserving Comments (/C) 


ma §€6Option 
/C 


The /C (for “comment”) option preserves comments during preprocessing. 
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If this option is not given, the preprocessor strips comments from a source 
file, since they do not serve any purpose in later stages of compiling. 


This option is valid only if the /E, /P, or /EP option is also used. 


m Example 


QCL /P /C SAMPLE.C 


This example produces a listing named SAMPLE.I. The listing file con- 
tains the original source file, including comments, with all preprocessor 
directives expanded or replaced. 


9.3.7.4 Searching for Include Files (/X) 


= Option 
/xX 


The /X option tells the compiler not to search for include files in the 
“standard places” defined by the DOS environment variable INCLUDE. 
This option lets you change the order in which the compiler searches for 
include files without changing the compiler environment you normally use. 


The. /X option is often used in conjunction with the /I option, which tells 
the compiler to search directories other than the standard places for in- 
clude files. For more information about specifying directories other than 
the standard places for include files, see Section 8.1.4.1, “Suppressing 
Compiler Warnings: The Warning Levels Options,” and Section 9.3.1, 
“Environment Options.” 


m@ Example 
QCL /X MAIN.C 
In the example above, the compiler looks for include files only in the cur- 


rent working directory, since the /X option tells QCL to consider the list 
of standard places empty. 


209 


Microsoft QuickC Compiler Programmer’s Guide 


9.3.8 Preparing for Debugging (/Zi, /Zd) 


=” Options 


/Zi Creates object file for in-memory debugging/CodeView debugger 
/Zd_ Creates object file with limited debugging information 


The /Zi option produces an object file containing full symbolic-debugging 
information for use with the debugger built into the QuickC environment 
or with the CodeView symbolic debugger. This object file includes full 
symbol-table information and line numbers. 


The /Zd option produces an object file containing line-number records 
corresponding to the line numbers of the source file. The /Zd option is 
useful in cases where you want to reduce the size of an executable file that 
you will be debugging with the CodeView debugger, and you do not need 
to use the expression evaluator during debugging. 


= Example 


QCL /Zi TEST.C 


This command produces an object file named TEST.OBJ that contains 
line numbers corresponding to the line numbers of TEST.C. 


9.3.9 Packing Structure Members (/Zp) 


= Options 


/Zp[f{1|2|4}] 
# pragma pack([{ 1]2/4} ]) 


When storage is allocated for structures, structure members are ordinarily 
stored as follows: 


e Items of type char or unsigned char, or arrays containing items 
of these types, are byte aligned. 


e Structures are word aligned; structures of odd size are padded to 
an even number of bytes. 


e All other types of structure members are word aligned. 
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To conserve memory, you may want to store structures more or less com- 
pactly. The /Zp option and the pack pragma control how structure data 
are “packed” into memory. Note that, on some processors, the /Zp option 
may slow program execution because of the time required to unpack struc- 
ture members when they are accessed. For example, on an 8086 processor, 
this option can reduce efficiency if members with int or long type are 
packed in such a way that they begin on odd-byte boundaries. 


Use the /Zp option to specify the same packing for all structures in a 
module. When you give the /Zp[n] option, where nis 1, 2, or 4, each 
structure member after the first 1s stored on an n-byte boundary, depend- 
ing on the option you choose. If you use the /Zp option without an argu- 
ment, structure members are packed on one-byte boundaries. 


Use the pack pragma when you want to specify packing other than the 
packing specified on the command line for particular structures. Give the 
pack(n) pragma, where nis 1, 2, or 4, before the declarations of structures 
that you want to pack differently. To reinstate the packing given on the 
command line, give the pack() pragma with no arguments. 


Table 9.5 shows the interaction of the /Zp option with the pack pragma. 


Table 9.5 
Using the pack Pragma 
Compiled with 

Syntax /Zp Option? Action 

# pragma pack() Yes Reverts to packing 
specified on the 
command line for 
structures that follow 

# pragma pack() No Reverts to default 


packing for structures 
that follow 


# pragma pack(n) Yes or no Packs the following 
structures to the given 
byte boundary until 
changed or turned off 


m Example 
QCL /Zp PROG.C 


This command causes all structures in the program PROG.C to be stored 
without extra space for alignment of members on int boundaries. 
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9.3.10 Suppressing Default-Library Selection (/Z]l) 


= Option 
VA 


Ordinarily QCL places the name of the default library, SLIBCE.LIB, in 
the object file. This mechanism allows the linker to automatically find the 
appropriate library to be linked with the object file. 


The /Zl option tells the compiler not to place the default library name in 
the object file. As a result, the object file is slightly smaller. 


The /ZI option is useful when you are using the LIB utility (described in 
Section 10.2) to build a stand-alone library. You can compile the object 
files you are putting in the library with /Zl to remove the library names 
before you combine them. Although the /Zl option saves only a small 
amount of space for a single object file, the total amount of space saved is 
significant in a library containing many object modules. 


m= Example 
QCL ONE.C /Zl TWO.C 
The example above creates the following two object files: 


e An object file named ONE.OBJ that contains the name of the C 
library SLIBCE.LIB 


e An object file named TWO.OBJ that contains no default-library 
information 


When ONE.OBJ and TWO.OBJ are linked, the default-library information 
in ONE.OBJ causes the given library to be searched for any unresolved 
references in either ONE.OBJ or TWO.OBJ. 


9.3.11 Controlling the 
Calling Convention (/Gc) 


# Options 
/Ge 


fortran 
pascal 
cdecl 
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The fortran, pascal, and cdecl keywords and the /Ge option control the 
function-calling and function-naming conventions that your programs use 
so that they can call and be called by functions written in Microsoft Pas- 
cal, FORTRAN, and BASIC. 


9.3.12 Setting the Data Threshold 


= Option 

/Gt[number] 

The /Gt option causes all data items whose size is greater than or equal 
to number bytes to be allocated in a new data segment. When number is 
specified, it must follow the /Gt option immediately, with no intervening 


spaces. When number is omitted, the default threshold value is 256. When 
the /Gt option is omitted, the default threshold value is 32,767. 


Note 


You can use the /Gt option only if you.are creating a compact- or 
large-model program, since small- and medium-model programs have 
only one data segment. 


9.3.13 Optimizing Loops (/Ol) 


= Option 

/O1 

The /Ol option tells the compiler to perform loop optimizations. When 
you choose this option, the compiler automatically places frequently used 


loop variables in registers to speed program execution. 


This option is turned on implicitly when you compile with the /Ox (maxi- 
mum optimization) option. | 
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9.4 Separate Compiling and Linking: 
QCL and LINK 


With the Microsoft QuickC Compiler you can link in several different 
ways. Sections 9.4.1—9.4.2 describe these methods. For each method, you 
specify the following information to the linker: 


e The object files you are linking 


e The names of the libraries you are linking with, if different from 
the default 


e The name of the executable file, if you want to rename it or use an 
extension other than .E. 


e The name of the map file, if you want to create one 


e The linker options, if any, that you are using to control the linking 
process 


To compile and link in two discrete steps, use the QCL command to com- 
pile source files without linking the resulting object files. Simply specify 
the /c option and give only the names of source files on the QCL com- 
mand line. Then link the resulting object files with the appropriate 
libraries and linker options in a separate step. 


9.4.1 Linking with the QCL Command 


To link with the QCL command, use this command syntax: 
QCL [option...] objfile... [lib...] /link link-option... lib... 


As described in Section 9.2, the QCL command bypasses compiling and 
invokes the linker if you give only object-file names on the command line. 
QCL passes the linker the object-file names, library names, and linker 
options you specify. 


9.4.2 Linking with the LINK Command 


If you are linking in a separate step, the alternative to using QCL is to 
invoke the linker directly by using the LINK command. Do this after 
compiling with QCL and the /c option. 


To link with the LINK command, your DOS environment should be set 


up as summarized below. For a full description, see Section 1.3.1.6 (for 
hard-disk users) or Section 1.3.2.4 (for floppy-disk users). 
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e If you are running LINK on a hard-disk system, use the DOS CD 
command to make the directory with the object files you are link- 
ing the current directory. 


e If you are running LINK on a floppy-disk system, the disk contain- 
ing your object files should be in drive B, and your working copy of 
the Work distribution disk in drive A. Make drive B the current 
drive. When you run LINK, type the drive name A: immediately 
before the LINK command, with no intervening spaces. During the 
linking process, you will be prompted to swap your working copy of 
the disk containing the appropriate stand-alone library in drive A. 


You can give the LINK command the input it needs in one of the follow- 


ing ways: 
Method 


Give input on 
the command 
line 


Respond to 
prompts 


Create a 
response file 


Instructions 


Use a command line of the following form: 
LINK objfile... [,fezefile] |, mapfile] [,[/eb]... |] [ink-ope]...[5] 


The command line cannot be longer than 128 char- 
acters. 


Type 
LINK 
and respond to the following prompts: 


Object Modules [.OBJ]: 
Run File [basename.EXE]: 
List File [NUL.MAP]: 
Libraries [.LIB]: 


To give more files for any prompt, type a plus sign 
(+) at the end of the line. The prompt reappears 
on the next line, and you can continue typing in- 
put for the prompt. 


Set up a file with responses to LINK command 
prompts, known as a “response file,” then type a 
LINK command of the form 


LINK @ filename 


where filename is the name of the response file. 

You can append linker options to any response or 
give options on one or more separate lines. The 
responses must be in the same order as the LINK 
prompts discussed above. You can also enter the 
name of a response file after any linker prompt, or | 
at any position in the LINK command line. 
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Table 9.6 shows the input you must give on the LINK command line, or 
in response to each prompt. 


Table 9.6 

Input to the LINK Command 

Field Prompt Input 

objfile Object Modules One or more object files that you are linking, 


separated by plus signs or spaces. You can also 
specify libraries in this field; in this case, all 
object modules in the library are linked with the 
other object files given in this field. 


exefile Run File Name of the executable file you are creating, if 
you want to give it a name or extension other. 
than the default. You should always use the 
files to have this extension. 


mapfile List File Name of the file containing a symbol map listing, 
if you are creating one. You can also give one of 
the following DOS device names to direct the map 
file to that device: AUX for an auxiliary device, 
CON for the console (terminal), PRN for a 
printer device, or NUL for no evice (so that no 
map file is created). See Section 9.5.10 for a 
sample map file and information about its 
contents. 


lib Libraries One or more stand-alone beatin or directories 
to be searched for stand-alone libraries, separated 
by plus signs or spaces. You can give up to 32 
libraries in response to the Libraries prompt; any 
additional libraries are ignored. See Section 
9.4.2.3 for rules for specifying library names to 


the linker. 
link-opt Give options after Any of the linker options described in Sections 
any response 9.5.1-9.5.14. Specify linker options anywhere on 


the command line. 


TYou can also create a map file with the QCL /Fm option (Section 9.3.2) or the LINK 
/MAP option (Section 9.5.10). 


9.4.2.1 Default Information for LINK 


You can choose defaults for information that LINK needs in any of the 
following ways: 
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Type of Default 


Command Line 


Prompt 
All remaining entries 


The following list shows the 
map files, and libraries: 


File Type 


Executable 


Map 


Libraries 


m= Examples 


STDEV SQROOT EXP 
/PAUSE /MAP 
STDVLST 
MATHEN.LIB 
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How to Choose 


Omit the file name or names before the entry 
and type only the required comma. The only 
exception to this is the default for the mapfile 
entry: if you use a comma as a placeholder for 
this entry, LINK will create a map file. 


Simply press ENTER. 


Type a semicolon after the applicable entry or 
prompt. (Note that you are required to give 
at least one object-file name as input.) 


defaults that LINK uses for executable files, 


Default 


Base name of the first object file given, plus 
the .EXE extension. To rename the execut- 
able file, give only the new base name; if you 
give a file name with no extension, LINK 
automatically appends the .EXE extension. 


The special file name NUL.MAP, which tells 
LINK not to create a map file. To create a 
map file, give only the base name; if you give 
a file name with no extension, LINK auto- 
matically appends the .MAP extension. 


Libraries named in the given object files. The 
library names placed in the object files depend 
on the floating-point and memory-model 
options that were given when the source files 
were compiled; see Table 9.4 for a list of the 
default names. If you specify a library other 
than the default library, give only the base 
name; if you give a library name with no 
extension, LINK automatically appends the 
-LIB extension. See Section 9.4.2.3 for infor- 
mation about specifying libraries other than 
default libraries. 
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This response file tells LINK to load the three object modules STDEV, 
SQROOT, and EXP. The executable file) STDEV.EXE, and the map file, 
STDVLST.MAP, are produced. The /PAUSE option causes LINK to pause 
before producing the executable file so that you can swap disks if neces- 
sary. The /MAP option tells LINK to include public symbols and ad- 
dresses in the map file. LINK also links any needed routines from the 
library file) MATHEN.LIB. See the discussion of the /PAUSE option in 
Section 9.5.2 and the discussion of the /MAP option in Section 9.5.10. 


LINK STDEV+SQROOT+EXP, ,STDVLIST, MATHEN.LIB 


In the example above, LINK loads and links the object modules 
STDEV.OBJ, SQROOT.OBJ, and EXP.OBJ, searching for unresolved 
references in the library file MATHFN.LIB. By default, the executable file 
isnamed STDEV.EXE. A map file called STDVLIST.MAP is also pro- 
duced. 


LINK 


Object Modules [.OBJ]: STDEV SQROOT EXP INP+ 
Object Modules [.OBJ]: READDATA+GRAPH+PRINT+ 
Object Modules [.OBJ]: REPORT 

Run File [STDEV.EXE]: 3; 


The example above illustrates how to continue any prompt by typing a 
plus sign (+) at the end of your response. The example above links all of 
the given object files, then creates an executable file. Since a semicolon 

is typed as a response to the Run File prompt, the executable file is 
given the default name: the base name of the first object file given (STDEV) 
plus the .EXE extension. The defaults are also used for the remaining 
prompts; as a result, no map file is created, and the default libraries 
named in the object files are used for linking. 


9.4.2.2 Specifying Files to LINK 

Most of the rules for specifying file names to LINK are the same as the 
rules for specifying file names to QCL: uppercase and lowercase letters 
can be used interchangeably, and file names can include path names to tell 
the linker to look for files or create files in the given path. However, the 
LINK command does not recognize wild-card characters in file names. 


9.4.2.3 Specifying Libraries to LINK 


Ordinarily, you do not need to give the linker a stand-alone-library name. 
When the QCL command creates object files, it places in each object file 
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the name of the correct stand-alone library for that object file. QCL 
determines which library name is appropriate based on the memory-model 
and floating-point options you give on the QCL command line, as de- 
scribed in Table 9.4 (Section 9.3.5). When the object file is passed to the 
linker, the linker looks for a library with the same name as the name in 
the object file and links the object file with that library automatically. 


To link object files with stand-alone libraries other than the defaults, you 
must tell the linker which libraries to link with. You can give the library 
names in any of the following places: 


e On the QCL command line. Library names appearing before /link 
must have .LIB extensions; library names appearing after /link 
may have blank extensions or no extensions. 


e In the fourth field of the LINK command line. 
e In response to the Libraries prompt of the LINK command. 


The linker searches libraries you specify to resolve external references 
before it searches default libraries. 


You might want to link with a stand-alone library other than the default 
if you want to do any of the following: 


e Link with additional stand-alone libraries. For example, if you did 
not include graphics functions in the libraries built by the SETUP 
program, you must link graphics programs with the stand-alone 
library GRAPHICS.LIB in addition to the default library. 


e Link with libraries in different paths. 


If you give a complete path name for the library, the linker looks 
only in that path for the library. Otherwise, it looks in the follow- 
ing locations, in the order shown: 


1. The current working directory. 


2. Any paths or drives that you give where you would ordinarily 
give library names. These paths or drives may be given after 
the /link option on the QCL command line, in the fourth field 
of the LINK command line, or in response to the Libraries 
prompt of the LINK command. 


3. The locations given by the LIB environment variable. 


e Ignore the library named in the object file; for example, if you want 
to link with uncombined libraries as described in Section 1.4. In 
this case, you must give the linker option /NOD in addition to 
specifying the library you want to use for linking. See Section 9.5.7 
for more information about the /NOD option. 
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= Example 
QCL STDEV SQROOT EXP /link C:\TESTLIB\ NEWLIBV3 


This example links three object modules to create an executable file named 
STDEV.EXE. The linker searches NEWLIBV3.LIB before searching the 
default libraries to resolve references. To locate NEWLIBV3.LIB and the 
default libraries, the linker searches the current working directory, then 
the C:\TESTLIB\ directory, and finally, the locations given by the LIB 
environment variable. 


9.4.2.4 LINK Memory Requirements 


LINK uses available memory for the linking session. If the files to be 
linked create an output file that exceeds available memory, LINK creates 
a temporary disk file to serve as memory. LINK creates the temporary file 
in the directory specified by the TMP environment variable. For example, 
if the TMP variable is set to C:\TEMPDIR, then LINK puts the tem- 
porary file in C:\TEMPDIR. If no TMP environment variable is defined, 
or if the directory specified by TMP does not exist, then LINK puts the 
temporary file in the current working directory. 


The temporary file is handled in one of the following ways, depending on 
the DOS version: 


1. When running on DOS Version 3.0 or later, LINK uses a DOS sys- 
tem call to create a temporary file with a unique name. 


2. When running on a version of DOS prior to 3.0, LINK creates a 
temporary file named VM.TMP. 


When LINK creates a temporary disk file, you will see the message 


Temporary file tempfile has been created. 
Do not change diskette in drive, letter 


Here, tempfile is “.\” followed by either VM.TMP or a name generated 
by DOS, and letter is the drive containing the the temporary file. 


If the drive named letter is a floppy-disk drive, the message Do not 
change diskette in drive also appears. If it appears, do not remove 
the disk from the drive until the linking session ends. If you remove the 
disk, linker operations will be unpredictable, and you may see the follow- 
ing message: 
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L1087: unexpected end-of-file on scratch file 
If you see this message, rerun the linker session. 


The temporary file that LINK creates is a working file only. LINK deletes 
it at the end of the session. 


9.5 Using Linker Options 


All linker options begin with the linker’s option character, the forward 
slash (/). Case is not significant in linker options; for example, /NOI and 
/noi are equivalent. 


To save space and effort, abbreviate linker options. However, be sure that 
your abbreviation is unique so that the linker can determine which option 
you want. (The minimum legal abbreviation for each option is indicated in 
the syntax of the option.) For example, several options begin with the 
letters “NO”; therefore, abbreviations for those options must be longer 
than “NO” to be unique. You cannot use “NO” as an abbreviation for the 
/NOIGNORECASE option, since the linker cannot tell which of the 
options beginning with “NO” you intend. The shortest legal abbreviation 
for this option is /NOI. 


Abbreviations must begin with the first letter of the option and must be 
continuous through the last letter typed. No gaps or transpositions are 
allowed. 


Some linker options take numeric arguments. A numeric argument can be 
any of the following: 


e A decimal number in the range 0 to 65,535. (Note that commas do 
not appear in numeric arguments.) 


e An octal number from 0 to 0177777. A number is interpreted as 
octal if it starts with “O.” For example, the number 10 isa 
decimal number, but the number O10 is an octal number, 
equivalent to 8 in decimal. 


e A hexadecimal number from 0 to OxFFFF. A number is interpreted 
as hexadecimal if it starts with Ox or OX. For example, Ox10 isa 
hexadecimal number, equivalent to 16 in decimal. 


Linker options affect all files in the linking process, regardless of where the 
options are specified. 
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9.5.1 Viewing the Options List (/HE) 


= Option 
/HE|LP] 


Use the /HE option to display a list of the available linker options. 


9.5.2 Pausing during Linking (/PAU) 


= Option 
/PAU[SE] 


The /PAU option tells the linker to pause in the link session and display 
a message before it writes the executable (.EXE) file to disk. This allows 
you to insert a new disk to hold the executable file. 


If you specify the /PAU option, LINK displays this message before it 
creates the executable file: 


About to generate .EXE file 
Change diskette in drive letter and press <ENTER> 


The letter is the current drive. LINK resumes processing when you press 
ENTER. 


Note 


Do not remove the disk containing the newly created list file or the 
disk used for the temporary file. 


If a temporary file is created on the disk you plan to swap, press 
CTRL+C to terminate the linking session. Rearrange your files so that 
the temporary file and the executable file can be written to the same 
disk. Then try linking again. 
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9.5.3 Displaying Linker-Process Information (/D) 


= Option 
/I[NFORMATION] 


This option is useful if you want to determine the locations of the object 

files being linked and the order in which they are linked. It displays infor- 
mation about the linking process, including each phase of linking and the 
names of the object files being linked. 


m Example 


x*x*zk* PASS ONE ««x+% 

HTOI .OBJ (htoi.c) 

*x*xkx LIBRARY SEARCH «2% 
c:\1lib\MLIBCE.LIB(chkstk) 
c:\lib\MLIBCE.LIB(crt0) 
c:\lib\MLIBCE.LIB (printf) 
c:\lib\MLIBCE.LIB (scanf) 


**x*x%* ASSIGN ADDRESSES «xxx 
x*x*k*k PASS TWO xxx 

HTOI .OBJ (htoi.c) 
c:\1ib\MLIBCE.LIB(chkstk) 
¢:\1lib\MLIBCE.LIB(crt0) 
c:\1ib\MLIBCE.LIB (printf) 
c:\1lib\MLIBCE.LIB(scanf) 


*%x*x*x WRITING EXECUTABLE «xx 


Segments 25 
Groups ek 
Bytes in symbol table 16400 


The example above shows a sample of the linker output when the /I 
option is specified on the LINK command line. 
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9.5.4 Preventing Linker Prompting (/B) 


m 8 Option 
/B[ATCH] 


The /B option tells the linker not to prompt you for a new path name 
whenever it cannot find a library or object file that it needs. When this 
option is used, the linker simply continues to execute without using the file 
in question. 


Using the /B option may cause unresolved external references during link- 
ing. This option is intended primarily for users who use batch or MAKE 
files to link many executable files with a single command and do not want 
the linker to stop processing if it cannot find a required file. 


This option does not prevent the linker from prompting for arguments 
that you do not give on the LINK command line. 


9.5.5 Creating Quick Libraries (/Q) 


ZH Option 
/Q[UICKLIB] 


The /Q option tells the linker to combine the object files and libraries you 
specify into a Quick library. Quick libraries have extensions of .QLB 
rather than .E-XE to distinguish them from executable files. When you 
start QuickC, you can give the /l option on the QC command line to load 
the Quick library. 


When you create a Quick library, the file name QUICKLIB.OBJ must be 
first in the list of object files to be linked. 


See Chapter 10, “Creating Quick Libraries and Stand-Alone Libraries,” for 
more information about creating and loading Quick libraries. 
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9.5.6 Packing Executable Files (/E) 


= Option 
/E[XEPACK] 


The /E option removes sequences of repeated bytes (typically null charac- 
ters) and optimizes the “load-time relocation table” before creating the 
executable file. The load-time relocation table is a table of references rela- 
tive to the start of the program. Each reference changes when the execut- 
able image is loaded into memory and an actual address for the entry 
point is assigned. 


Executable files linked with this option may be smaller and load faster 
than files linked without this option. However, you cannot debug packed 
programs with the debugger built into the QuickC programming environ- 
ment or with the Microsoft CodeView window-oriented debugger. 


9.5.7 Ignoring Default Libraries (/NOD) 


= Option 
/NOD|[EFAULTLIBRARYSEARCH] 


The /NOD option tells the linker not to search any library specified in an 
object file to resolve external references. 


In general, QuickC programs do not work correctly without the stand- 
alone libraries built by the SETUP program. Thus, if you use the /NOD 
option, you should give the name of the required stand-alone library expli- 
citly. | 


9.5.8 Setting Maximum Number 


of Segments (/SE) 
=H Option 
/SE[GMENTS]:number 


The /SE option controls the number of segments that the linker allows a 
rogram to have. The default is 128, but you can set number to any value 
decinal, octal, or hexadecimal) in the range 1-3072 (decimal). 


225 


Microsoft QuickC Compiler Programmer’s Guide 


For each segment, the linker must allocate space to keep track of segment 
information. When you set the segment limit higher than 128, the linker 
allocates more space for segment information. For programs with fewer 
than 128 segments, you can minimize the amount of storage the linker 
needs by setting number to reflect the actual number of segments in the 
program. The linker displays an error message if this number is too high 
for the amount of memory the linker has available. 


9.5.9 Setting the Maximum | 
Allocation Space (/CP) 


a Option 

/CP[ARMAXALLOC]:number 

The /CP option sets the maximum number of 16-byte paragraphs needed 
by the program when it is loaded into memory to number, an integer in the 
range 1-65,535. The operating system uses this value when allocating 
space for the program before loading it. The Microsoft C start-up module 
cuts memory back to the larger of the following two values: 


e 64K 
e The amount of memory specified in this option 


For programs with limited static data and heap usage, this option is 
unnecessary. 


9.5.10 Creating a Map File (/M, /LI) | 


=” Option 

/M[AP][: number] 

/LI[NENUMBERS] 

The /M and /LI options create a map file. A map file lists the segments of 


a program in their order of appearance in the load module. A sample map 
file is shown below: 


Start Stop Length Name Class 
OOOOOH O1E9FH O1EAOH _TEXT CODE 


O1EAOH OLEAOH OOOOOH C_ETEXT ENDCODE 
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The information in the Start and Stop columns shows the 20-bit 


address 


load mo 


in hexadecimal 


) of each segment, relative to the beginning of the 
ule. The load module begins at location zero. The Length _ 
column gives the length of the segment in bytes. The Name column gives 


the name of the segment, and the Class column gives information about 
the segment type. See your DOS programmer’s documentation for infor- 
mation about groups, segments, and classes. 


The starting address and name of each group appears after the list of seg- 
ments. A sample group listing is shown below: 


Origin 
O1EA:0 


Group 
DGROUP 


In the example above, DGROUP is the name of the data group. D@ROUP 


is the only group used by programs compiled with the Microsoft QuickC 


Compiler. 


If you link with the /LI option, the map file shows the line numbers of 
your source program and the address associated with each line number, as 
shown in the following example: 


Line numbers for HTOI.OBJ(htoi.c) segment _TEXT 


2 0000:0010 4 0000:0019 5 0000:0023 6 0000:0031 
7 0000 :0047 10 0000:004B 12 O0000:0054 13 0000:005A 
14 0000: OO5F 16 0000:0067 17 0000: 0070 18 0000:0078 
19 0000 :007D 20 0000:008A 21 0000: 008D 22 O000:008F 
23 0000:0095 25 0000:009A 26 0000: 009D 28 0000:00A5 
29 0000:00C2 30 0000:00C5 32 0000:00CA 33 0000:00D2 
36 O000:00D6 38 O000: 00DF 40 0000:00E9 42 0000:0107 


43 0000:010F 


If you link with the /M option, the map file contains two lists of global 
symbols: the first sorted in ASCII-character order by symbol name and the 
second by symbol address. The notation Abs appears next to the names 
of absolute symbols (symbols containing 16-bit constant values that are 
not associated with program addresses). 


Each list can contain a maximum of 2048 sorted symbols. You can give the 
number argument with the /M option to list more symbols sorted by 
address. The number argument can be any decimal, octal, or hexadecimal 
number between 0 and 65,535 (decimal), inclusive; however, in practice, 
the number of sorted symbols is limited by the amount of near heap space. 
If you give a number argument, the Publics by Name list does not 
appear in the map file. 
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Address Publics by Name 
OLEA: 0096 STKHQQ 

0000: 1D86 _brkctl 
O1EA:04BO _edata 
O1EA:0910 _end 

O1EA:00EC __abrkp 
O1LEA:009C __abrktb 
O1LEA:00EC __abrktbe 


0000:9876 Abs __acrtmsg 
0000:9876 Abs __acrtused 


"O1EA:0240 ___arge 
O1EA:0242 ___ argv 

Address Publics by Value 
0000 :0010 _main 

0000 :0047 _htoi 

0000 :OODA _exp16 

0000 :0113 __chkstk 

0000 :0129 __astart 


0000 :01C5 __cintDIV 


Many of the global symbols that appear in the map file are symbols used 
internally by the Microsoft QuickC Compiler. These symbols usually begin 
with one or more leading underscores or end with QQ. 


The addresses of the external symbols are in the frame:offset format, show- 
ing the location of the symbol relative to zero (the beginning of the load 
module). 


For both the /LI and the /M options the map file gives the program entry 
point, as shown in the following example: 


Program entry point at 0000:0129 


You can also create a map file by giving the /Fm option on the QCL 
command line, by giving a map-file name on the LINK command line, or 
by giving a map-file name in response to the List File prompt. These 
ae do not allow you to increase the number of symbols sorted by 
address. 
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9.5.11 Controlling the Stack Size (/ST) 


” Option 

/ST[ACK]:number 

The /ST option specifies the size of the stack for your program, where 
number is any positive decimal, octal, or hexadecimal value up to 65,535 
(decimal) representing the size, in bytes, of the stack. Give octal or hexa- 
decimal numbers by using the usual C format, octal numbers beginning 
with “O” and hexadecimal numbers beginning with “Ox”. 


If you do not specify this option, the start-up routine in the stand-alone C 
library sets the default stack size to 2K. 


If you get a stack-overflow message, you may need to increase the size of 
the stack. In contrast, if your program uses the stack very little, you can 
save some space by decreasing the stack size. 


This option has the same effect as the /F option of the QCL command. 


= Example 
LINK FACT.OBJ EXP.OBJ,,, /STACK:0xCOO 


This example sets the stack size to COO hexadecimal (3K decimal) for the 
program created by linking the FACT.OBJ and EXP.OBJ object files. 


9.5.12 Translating Far Calls (/F, /NOF) 


# 8@6Options 
/F[ARCALLTRANSLATION] 


/NOF[ARCALLTRANSLATION] 


The /F linker option tells the linker to optimize far calls to procedures 
that lie in the same segment as the caller. This option results in slightly 
faster, more compact programs. 


When you specify the /F linker option, the linker optimizes 32-bit calls to 
procedures in the same segment as the calling procedure. Since the seg- 
ment addresses of the calling and called procedures are the same, only a 
16-bit call is required. If the /F linker option is given, the linker removes 
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the far call and replaces it with code that first places the contents of the 
CS register on the stack, then makes a near call. The called procedure still 
returns with a far (32-bit) return instruction. However, because both the 
code segment (stored in CS) and the near address are on the stack, the far 
return is done correctly. The linker also adds a NOP instruction; conse- 
quently, the five-byte far call is replaced by exactly five bytes of instruc- 
tions. 


Although the linker does not use far-call translation unless you explicitly 

ask for it, you can use the /NOF option to turn off far-call translation if, 
for example, you have given the /F linker option in the CL environment 

variable. 


9.5.13 Packing Contiguous 
Segments (/PAC, /NOP) 


= Options 
/PAC|[KCODE]|:number] 


/NOP[ACKCODE] 


The /PAC option tells the linker to group neighboring code segments. 
Code segments in the same group share the same segment address; all 
offset addresses are then adjusted upward as needed. As a result, many 
instructions that would otherwise have different segment addresses share 
the same segment address. 


Used in conjunction with the /F linker option (described in Section 
9.5.12), the /PAC option can reduce the size and improve the efficiency of 
medium-model programs. 


If specified, number is the size limit of groups formed by /PAC. The 
linker stops adding segments to a particular group as soon as it cannot 
add a segment to the group without exceeding number. At that point, the 
linker starts forming a new group with the remaining code segments. If 
number is not given, the default is 65,530. 


Although the linker does not pack neighboring segments unless you expli- 
citly ask for it, you can use the /NOP option to turn off segment packing 
if, for example, you have given the /PAC option in the CL environment 
variable. 
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9.5.14 Other LINK Options 


Not all options of the LINK command are suitable for use with QuickC 
programs. The following linker options can be used with Microsoft QuickC 
programs, but they are never required, since they request actions that the 
QCL command or the Microsoft QuickC Compiler performs automati- 
cally: 


/CO[DEVIEW] 

Prepares an executable file to be debugged within the QuickC environment 
or by using the CodeView window-oriented debugger. If you are compiling 
and linking in separate steps, this option has an effect only if you are link- 
ing object files compiled with the /Zi option. 

/LI[NENUMBERS] 


Creates a map file and includes the line numbers and associated addresses 
of the source program. If you are compiling and linking in separate steps, 
this option has an effect only if you are linking object files compiled with 

the /Zd option. 

/NOI[GNORECASE] 


Tells the linker to distinguish between uppercase and lowercase letters; for 
example, the linker would consider ABC, abc, and Abc to be three sepa- 
rate names. If you want to link without using /NOI, you must invoke the 
linker in a separate step with the LINK command. 

/DO|[SSEG] 


Forces segments to be ordered using the defaults for Microsoft high-level 
language products. QuickC programs always use this segment order by 
default. 


Do not use the following linker options when linking object files compiled 
with the Microsoft QuickC Compiler. They are suitable only for object 
files created by the Microsoft Macro Assembler (MASM). 


/DS|ALLOCATE] 

Loads all data starting at the high end of the default data segment. 
/HI|GH] 

Places the executable file as high in memory as possible. 


/NOG[ROUPASSOCIATION] 


Tells the linker to ignore group associations when assigning addresses to 
data and code items. 
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/O[VERLAYINTERRUPT]:number 


Specifies an interrupt number other than Ox3F for passing control to 
overlays. 


9.6 Controlling Stack and Heap Allocation 


Programs compiled and linked under Microsoft C run with a fixed stack 
size (the default size is 2048 bytes). The stack resides above static data, 
and the heap uses whatever space is left above the stack. However, for 
some programs a fixed-stack model may not be ideal; a model where the 
stack and heap compete for space is more appropriate. 


Linking with the mVARSTCK.OBJ object files gives you such a model: 
when the heap runs out of memory, it tries to use available stack space 
until it runs into the top of the stack. When the allocated space in the 
stack is freed, it is once again made available to the stack. Note that the 
stack cannot grow beyond the last-allocated heap item in the stack or, if 
there are no heap items in the stack, beyond the size it was given at link 
time. Note also that while the heap can employ unused stack space, the 
reverse is not true: the stack cannot employ unused heap space. 


You can change the model used to allocate heap space by linking your pro- 
gram with one of the mVARSTCK.OBJ object files (where m is the first 
letter of the library you choose). These files are the small-, medium-, 
compact-, and large-model versions of a routine that allows the memory- 
allocation functions (malloc, calloc, _expand, —fmalloc, — nmalloc, 
and realloc) to allocate items in unused stack space if they run out of 
other memory. 


When you link your program with one of the nVARSTCK.OBJ files, do 
not suppress stack checking with the #check_ stack pragma, or the /Gs 
or /Ox option. Stack overflow can occur more easily in programs that use 
this option, possibly causing errors that would be difficult to detect. 


m= Example 
QCL TEST.C SVARSTCK 
This command line compiles TEST.C and then links the resulting object 


module with SVARSTCK.OBJ, the variable-stack object file for small- 
model programs. 
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9.7 Using Overlays 


If you are not sure that a program will fit in available memory, you can 
direct LINK to create an overlaid version of the program. In an overlaid 
version of a program, specified parts of the program (known as “overlays” ) 
are loaded only if and when they are needed. These parts share the same 
space in memory. Only code is overlaid; data are never overlaid. Programs 
that use overlays usually require less memory, but they run more slowly 
because of the time needed to read the code from disk into memory. 


Specify overlays by enclosing them in parentheses in the list of object files 
that you give the linker. Each module or combination of modules in paren- 
theses represents one overlay. For example, you could give the following 
object-file list in the objfiles field of the LINK command line: 


a + (bt+c) + (et+f) + g + (3) 


In this example, the modules (b+c), (e+f), and (i) are overlays. 
Whenever control passes to these modules, they are read into memory 
from disk. The a and g modules, and any modules drawn from the 
libraries, constitute the “resident part” (or “root”) of your program. 


Overlays are loaded into the same region of memory, so only one can be 
resident at a time. Duplicate names in different overlays are not sup- 
ported, so each module can appear only once in a program. 


The linker replaces calls from the root to an overlay, and calls from an 
overlay to another overlay with an interrupt (followed by the module 
identifier and offset). By default, the interrupt number is 63 (3F hexade- 
cimal). You can use the /O linker option to change the interrupt number. 
The /O option should be used only by programs that use overlays and 
spawn another program using overlays. In this case, each program should 
use a separate overlay-interrupt number, meaning at least one of the pro- 
grams should be linked with this option. 


9.7.1 Restrictions on Overlays 


You can overlay only modules to which control is transferred and returned 
by a standard 32-bit call/return instruction. However, calls to functions 
defined with the near keyword are 16-bit calls. This means that you can- 
not overlay modules containing near functions if other modules call those 
subroutines. 
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9.7.2 Overlay-Manager Prompts 


The overlay manager is part of the standard libraries provided with the 
Microsoft QuickC Compiler. If you specify overlays during linking, the 
code for the overlay manager is automatically linked with the other 
modules of your program. 


When the executable file is run, the overlay manager searches for that file 
whenever another overlay needs to be loaded. The overlay manager first 
searches for the file in the current directory; then, if it does not find the 
file, the manager searches the directories listed in the PATH environment 
variable. When it finds the file, the overlay manager extracts the overlay 
modules specified by the root program. If the overlay manager cannot find 
an overlay file when needed, it prompts the user to enter the file name. 


Even with overlays, the linker produces only one .EXE file. This file is 
opened again and again, as long as the overlay manager needs to extract 
new overlay modules. 


For example, assume that an executable program called PAYROLL. EXE, 
which does not exist in either the current directory or the directories 
specified by PATH, uses overlays. If the user runs it by entering a com- 
plete path specification, the overlay manager displays the following mes- 
sage when it attempts to load overlay files: 


Cannot find PAYROLL.EXE 
Please enter new program spec: 


The user can then enter the drive or directory, or both, where the program 
PAYROLL.EXE is located. For example, if the file is located on drive B in 
the directory \EMPLOYEE\DATA\ the user could enter either 
ey er or simply \EMPLOYEE\DATA\ if the current drive 
is 

If the user later removes the disk in drive B and the overlay manager needs 
to access the overlay again, it will not find PAYROLL.EXE. The following 
message will be displayed: 


Please insert diskette containing B:\EMPLOYEE\DATA\PAYROLL.EXE 
in drive B: and strike any key when ready. 


After the overlay file has been read from the disk, the overlay manager 
displays the following message: 


Please restore the original diskette. 
Strike any key when ready. 
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Creating Quick Libraries and Stand-Alone Libraries 


Libraries are collections of routines that have been compiled or assembled 
to create a set of object modules that can be used by QuickC programs. 
The QuickC package provides tools for creating and maintaining two 
types of libraries, easily distinguishable by their characteristic file-name 
extensions: 


Extension Function 


-QLB Generally referred to as a “Quick” library, this 
type of library, created with the LINK utility, is 
used for programs compiled and run within the 
QuickC programming environment. 


.LIB The .LIB extension characterizes a library created 
by the LIB library manager. These libraries are 
generally referred to as “stand-alone” libraries and 
have the same format as libraries shipped with 
other Microsoft high-level-language products. 


10.1 Quick Libraries 


Quick libraries are used for programs that are compiled and run within the 
QuickC programming environment. Load a Quick library when you want 
to supplement the list of standard C library routines that are built into 
the QuickC programming environment. 


10.1.1 Creating Quick Libraries 


You can combine object files, stand-alone libraries, or any combination of 
the two into a Quick library. When you include a stand-alone library in a 
Quick library, all of the modules in that library become part of the Quick 
library. 


Follow these steps to create a Quick library: 


1. Compile the C source files that you want to include in the library. 
Since modules in a Quick library must use the medium memory 
model, either compile from the QuickC programming environment 
and choose the Obj output option, or compile using the /AM 
option on the QCL command line. 


2. Invoke the linker, either from the QCL command line or by using 
the LINK utility. Give QUICKLIB.OBJ as the first object-file 
name on the command line or in response to the Object Files 
prompt. (QUICKLIB.OBB3J is on the Libraries #1 distribution 
disk in the QuickC package.) Then give the names of the object 
files and stand-alone libraries you are combining. Give the name of 
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the Quick library as the name of the executable file on the com- 
mand line, or in response to the Run File prompt. Specify the /Q 
linker option to create the Quick library. 


mg Example 


QCL QUICKLIB /AM CRCL.C ELPS.C LINE.C CRV.C /FeSHAPES.QLB /link /Q 
The QCL command line above creates a Quick library named 


SHAPES.QLB from the source files CRCL.C, ELPS.C, LINE.C, and 
CRV.C. 


10.1.2 Loading Quick Libraries 


To load a Quick library when you start QuickC, use a command line of the 
following form: 


QC /Iglibname: 


In this command line, glibname is the base name of the Quick library (the 
name without the .QLB extension). If the Quick library has a different 
extension, you must give the file name with that extension. 


Quick libraries, if used, must be loaded when you start the QuickC envi- 
ronment. You can load only one Quick library each time you start QuickC. 


QuickC searches for the Quick libraries in the following locations, in the 
order shown: 


1. The path specified in the Quick-library name, if any. 
2. The current directory. 
3. The path specified by the LIB environment variable. (See your 


DOS user’s guide for information about environment variables.) 
mg Example 
QC /1GRAPHICS.QLB 
The command above loads the Quick library GRAPHICS.QLB, which 


contains the QuickC graphics functions. (This Quick library is provided as 
part of the QuickC package.) 
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10.1.3 Standard Library Routines 
in Quick Libraries 


Table 6.1 in Section 6.1.1, “Single-Module Programs,” lists the standard C 
library routines that are built into the QuickC environment. You can call 
these routines in your programs without loading a Quick library. 


As you can see from Table 6.1, many of the standard C library routines 
are defined within the QuickC environment. However, if your program uses 
standard library routines that are not defined within the QuickC environ- 
ment, you have several choices. 


If your program uses library routines (for example, getchar()) that are 
implemented as macros, simply copy an # include directive for the appro- 
priate header file into your source file. — 


If your program calls library functions, use the following procedure to 
create and load a Quick library containing these functions: 


1. Create a source file containing a main program that consists only 
of calls to the library routines that you want in the Quick library. 
For example, if you wanted to create a Quick hbrary containing 
the BIOS-interface routines in the Microsoft C run-time library, 
you might create the following source file named BIOS.C: 


#include <bios.h> 
main () 


_bios_serialcom() ; 
_bios_disk(); 
_bios_equiplist(); 
_bios_keybrd(); 
_bios_memsize(); 
_bios_printer (); 
_bios_timeofday (); 
} 


Note that the compiler may display warnings because no actual 
arguments are passed to the funtions in the program. 


2. Compile and link the source file as described in Section 10.1.1. In 


this example, you could use the QCL and LINK commands as 
shown below: 
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QCL /c /AM BIOS.C 


LINK QUICKLIB.OBJ+BIOS.OBJ,BIOS.QLB, , /Q: 
3. Load the resulting Quick library as usual. In this example, use the 
following command: 


QC /1BIOS 


10.2 Managing Stand-Alone Libraries: 
the LIB Utility 


The Microsoft Library Manager, LIB, is used to manage the contents of 
stand-alone libraries. A stand-alone library is made up of “object 
modules” —that is, object files that have been combined to form a library. 
Unlike an object file, an object module does not exist independently of the 
library it belongs to, and it does not have a path name or extension associ- 
ated with its file name. Use LIB to 


e Combine object files to create a new library 
e Add object files to an existing library 


e Delete or replace the object modules of an existing library 


e Extract object modules from an existing library and place them in 
separate object files 


e Combine the contents of two existing libraries into a new library 
Object files, stand-alone libraries, XENIX archives, Intel-style libraries, or 
any combination of these can be combined to form a stand-alone library. 


Stand-alone libraries are usually identified by their .LIB extension, though 
other extensions are allowed. 


When updating an existing library, LIB performs all of its operations on a 


copy of the library. This mechanism ensures that you have a backup copy 
of any library you update. 


10.2.1 Running LIB 


If you are running LIB on a hard-disk system, use the DOS CD command 
to make the current directory that directory where you have stored the 
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object files or libraries you are working with. If you are running LIB on a 
floppy-disk system, place your working copy of the Libraries #1 distribu- 
tion disk in drive A and the disk containing the object files or libraries you 
are working with in drive B. 


Give the LIB command the input it needs in one of the following ways: 


e By giving the input on a command line of the form 
LIB oldlib [/P[AGESIZE]:number] [commands], [listfile]], | newl2b] |] [5] 
The command line cannot be longer than 128 characters. 
e By typing 
LIB 
and responding to the prompts 


Library name: 
Operations: 
List file: 
Output library: 


To give more files for any prompt, type an ampersand (&) at the 
end of the line. The prompt reappears ‘on the next line, and you 
can continue typing your response to the prompt. 


e By setting up a file with responses to LIB command prompts, 
known as a “response file,” then typing a LIB command of the 
form 


LIB @ filename 


where filename is the name of the response file. The responses must 
be in the same order as the LIB prompts discussed above. You can 
also enter the name of a response file after any linker prompt, or at 
any position in the LIB command line. 


Table 10.1 shows the input you give on the LIB command line, or in 
response to each prompt. 
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Table 10.1 

Input to the LIB Command 

Field Prompt Input 

oldlib Library name Name of the library you are changing or 


creating. If this library does not exist, LIB 
asks if you want to create it. Type y to 
create a new library or n to terminate LIB. 
This message is suppressed if you type 
command characters, a comma, or a semi- 
colon after the library name. A semicolon 
tells LIB to perform a consistency check on 
the library; with the library and display, it 
displays a message if it finds errors in any 
library module. 


/P:number  /P:number in Sets the page size for the library to number 
response to “Library — bytes, where number is an integer power of 
name” prompt 2 between 16 and 32,768, inclusive. See 


Section 10.2.5 for more information about 
the library page size. 


commands Operations Command symbols and object files that tell 
LIB what changes to make in the library. 

listfile List file Name of a cross-reference-listing file. No 
listing file is created if you do not give a file 
name. . 

newlib Output library Name of the changed library that LIB 


creates as output. If you do not give a new 
library name, the original, unchanged 
library is saved in a library file with the 
same name but with a .BAK extension 
replacing the .LIB extension. 


10.2.2 Defaults for LIB 


Choose defaults in any of the following ways for the information that LIB 
needs: 


e Tochoose the default for any command-line entry, omit the file 
name or names before the entry and type only the required comma. 
The only exception to this is the default for the listfile entry: if you 
use a comma as a placeholder for this entry, LIB will create a 
cross-reference-listing file. 
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e To choose the default for any prompt, press ENTER. 


e Tochoose the defaults for all remaining command-line entries, or 
for all remaining prompts, type a semicolon (;) after those entries 
or prompts. The semicolon should be the last character on the 


command line. 


The following list shows the defaults that LIB uses for cross-reference- 
listing files and output libraries: 


File 


Cross-reference 
listing 
Output library 


Default 
The special file name NUL, which tells LINK 
not to create a cross-reference-listing file 


The oldlzb entry or the response to the 
“Library name” prompt 


10.2.3 Command Symbols 


To tell LIB what changes you want to make to a library, type a command 


symbol (such as +, — 


—+, *, or —*), followed immediately by a module 


name, object-file name, or library name. You can specify more than one 


operation, in any order. 


The following list shows each LIB command symbol, the type of file name 
to specify with the symbol, and what the symbol does: 


Command 


+{ objfile|lib} 


—module 


Meaning 


If given with an object-file name, the plus sign 
(+) adds the given object file to the input 
library and makes that object file the last 
module in the library. You can use a path 
name for the object-file name. Since LIB 
automatically supplies the .OBJ extension, 
you can omit the extension from the object- 
file name. 


If given with a library name, the plus sign (+) 
adds the contents of that library to the input 
library. The library name must have the .LIB 
extension. 


Deletes the given module from the input 


library. A module name has no path name 
and no extension. 
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—+module Replaces the given module in the input 
library. Module names have no path names 
and no extensions. LIB deletes the given 
module, then appends the object file that has 
the same name as the module. The object file 
is assumed to have an .OBJ extension and to 
reside in the current working directory. 


«x module Copies the given module from the library to 
an object file in the current working direc- 
tory. The module remains in the library file. 
When LIB copies the module to an object file, 
it adds the .OBJ extension. You cannot over- 
ride the .OBJ extension, drive designation, or 
path name given to the object file. However, 
you can later rename the file or copy it to 
whatever location you like. 


—* module Moves the given object module from the 
library to an object file. This operation is 
equivalent to copying the module to an object 
file, as described above, then deleting the 
module from the library. 


Warning 


Library modules may contain calls to other library modules. If you 
extract library modules that call other library modules, the called 
modules are not extracted. 


= Examples 
LIB LANG-+HEAP; 


The example above uses the replace command symbol (—+) to instruct 
LIB to replace the HEAP module in the library LANG.LIB. LIB deletes 
the HEAP module from the library, then appends the object file 

HEAP .OBJ as a new module in the library. The semicolon at the end of the 
command line tells LIB to use the default responses for the remaining 
prompts. This means that no listing file is created and that changes are 
written to the original library file instead of to a new library file. 
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LIB LANG-HEAP+HEAP ; 
LIB LANG+HEAP-HEAP; 


The examples above perform the same function as the first example in this 
section, but in two separate operations, using the add (+) and delete (—) 
command symbols. The effect is the same for these examples because 
delete operations are always carried out before add operations, regardless 
of the order of the operations in the command line. This order of execution 
prevents confusion when a new version of a module replaces an old version 
in the library file. 


LIB FOR; 


The example above causes LIB to perform a consistency check of the 
library file FOR.LIB. No other action is performed. LIB displays any con- 
sistency errors it finds and returns to the operating-system level. 


LIB LANG, LCROSS.PUB 


This example tells LIB to perform a consistency check of the library file 
LANG.LIB and then create a cross-reference-listing file that is named 
LCROSS.PUB. ; 


LIB FIRST -*STUFF *MORE, ,SECOND 


The example above instructs LIB to move the module STUFF from the 
library FIRST.LIB to an object file called STUFF .OBJ. The module 
STUFE is removed from the library in the process. The module MORE is 
copied from the library to an object file called MORE.OBJ; the module 
remains in the library. The revised library is called SECOND. LIB. It con- 
tains all the modules in FIRST.LIB except STUFF, which was removed 
by using the move command symbol (—*). The original library, 
FIRST.LIB, remains unchanged. 


LIBFOR 
+CURSOR+HEAP -HEAP *FOIBLES 
CROSSLST 


The contents of the above response file cause LIB to delete the module 
HEAP from the LIBFOR.LIB library file, extract the module FOIBLES 
and place it in an object file named FOIBLES.OBJ, and append the 
object files CURSOR.OBJ and HEAP.OBJ as the last two modules in the 
library. Finally, LIB creates a cross-reference-listing file named 
CROSSLST. 
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10.2.4 Cross-Reference-Listing Files 


A cross-reference-listing file contains the following two lists: 


1. An alphabetical list of all public symbols in the library. 


Each symbol name is followed by the name of the module in which 


it is referenced. 


2. Alist of the modules in the library. 


Under each module name is an alphabetical listing of the public 


symbols defined in that module. 


= Example 


The examples here show parts of the cross-reference-listing file for the 
standard C library MLIBCE.LIB. In the part immediately below, the first 
and third columns show the public symbols in the library, and the second 
and fourth columns show the names of the modules where the symbols are 


referenced: 

SSOVLINIT... secs ovlm61 
$i8_implicit_exp..emfin 

S18 ANpue c+ 60.6 e608 emfin 

SO NG ic gceeiantei'e te vd aie ixtomx 
$i8. tpwrlO.. 2.6. <« emtmul 
SmMB_i8B..wcececevece ixtomx 
DOSDEVCONFIG...... apisim 


DOSGETMACHINEMODE. .apisim 


S242 M10 iid wis wie ixtomx 
SiG. inpbhasicdss.4 6 ss emfin 
$i8_input_ws...... emfin 
S18. OUCbUE as sa es emfout 
SiG og ave esos. ae hes ixtomx 
DOSCREATECSALIAS. .apisim 
DOSEREESEG:s. 2) «)0'4rs apisim 


DOSSETVEC . @ ews 6 es apisim 


In the second part of the listing, shown below, each module of the library 
is followed by the public symbols that appear in each module: 


afhdiff Offset: OOOOOO1OH Code and data size: 41H 
__aFahdiff 

anhdiff Offset: OOOOOCOdOH Code and data size: 3dH 
__aNahdiff 

3_file Offset: OOOOO190H Code and data size: liaH 
__iob __iob2 __lastiob 

access Offset: OOOOO2fOH Code and data size: i1fH 
_access 
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10.2.5 Setting the Library Page Size 


The page size of a library affects the alignment of modules stored in the 
library. Modules in the hbrary are always aligned to start at a position 
that is a multiple of the page size (in bytes) from the beginning of the file. 
The default page size for a newly created library is 16 bytes. 


You can set a different library page size while you are creating a library or 
change the page size of an existing library by adding the following option 
after the oldlzb entry on the LIB command line or after the name you type 
in response to the “Library name” prompt: 


/P[AGESIZE]:number 


The number specifies the new page size. It must be an integer value 
representing a power of 2 in the range 16 to 32,768. 


The library page size determines the number of modules the library can 
hold; thus, increasing the page size allows you to include more modules in 
the library. However, the larger the page size, the larger the amount of 
wasted storage space in the library (on average, pagesize/2 bytes per 
meet). In most cases you should use a small page size unless your library 
is very large. 


The page size also determines the maximum size of the library. This limit 


is number * 65,536. For example, if you specify /P:16, the library must be 
smaller than one megabyte (16 * 65,536 bytes). 
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Automating Program Development with MAKE 


The MAKE program-maintenance utility can help you develop programs 
containing more than one module. MAKE automatically updates a file 
whenever it is out of date with respect to other, related files. MAKE is 
especially useful in situations such as the following: 


e In program development, MAKE can automatically update an 
executable file whenever any of the source or object files is altered. 


e In library management, MAKE can automatically rebuild a li- 
brary whenever any of the modules in the library is altered. 


e In anetworking environment, MAKE can automatically update a 
local copy of a program or file that is stored on the network when- 
ever the master copy has been updated. 


When you run MAKE, you must give it the name of a file. This file, 
known as a “MAKE description file,” contains instructions that tell 
MAKE which files to update, which files must change before it performs 
the update, and what kind of updating to perform. A description file 
might contain the following data: 


TEST.EXE: TEST.C TEST2.C 
QCL TEST.C TEST2.C 


In this example, TEST.EXE is the file to be updated whenever either of 
the source files TEST.C or TEST2.C is altered. The actual updating is 
performed by the QCL command on the following line. See Section 11.1 
for more information about description files. 


The QuickC environment automatically builds a description file for pro- 
grams that you compile within the environment. 


Section 11.2 describes the information you can give with the description- 
file name on the MAKE command line, including MAKE options. Sec- 
tions 11.3-11.4 describe more advanced features of the MAKE utility. 


11.1 The Heart of MAKE: 
Description Files 


The MAKE utility relies on “description files” to determine which files to 
update, when to update them, and what operations to perform. AMAKE 
description file consists of one or more “description blocks,” each of which 
gives this information for a single file. 


Section 11.1.1 shows how to create a simple description file consisting of a 
single description block. | 
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Sections 11.1.1-11.1.2 explain the format of a description block, the rules 
to follow in setting one up, and guidelines for specifying description blocks 
in a description file. 


Section 11.1.2 discusses the MAKE description files that the QuickC envi- 
ronment builds for programs created within the environment. 


11.1.1 Building a MAKE Description File 


To illustrate how the MAKE utility works, this section describes how to 
build a simple MAKE description file. Since a MAKE description file is a 
text file, you can use any text editor to create one. 


In this example, assume that you want to update an executable file named 
UPDATE.EXE whenever any of its source files are changed. Assume further 
that the names of these source files are GETINPUT.C, FINDREC.C, and 
UPDATE.C. Use the following procedure to create a MAKE description 
file to update UPDATE .EXE automatically: 


1. Using the text editor, create a file named UPDATE. Although a 
MAKE description file can have any name, you may find it helpful 
to give the description file the same name (without an extension) as 
the file it maintains. 


2. Type the name of the file you are maintaining followed by a colon, 
as shown below. This file is known as the “outfile,” since MAKE 
creates the updated version of the file as output. (Outfiles are 
sometimes known as “target files.” ) 


UPDATE.EXE : 


3. Following the colon, type the names of any files that, when 
changed, should cause the outfile to be updated. In this example, 
you want to update UPDATE.EXE whenever GETINPUT.C, 
FINDREC.C, or UPDATE.C is changed, so the line in the descrip- 
tion file would look like this: 


UPDATE.EXE : UPDATE.C GETINPUT.C FINDREC.C 


The files to the right of the colon are known as “infiles” since 
MAKE uses them as input to determine whether or not to update 
the outfile. (Infiles are sometimes known as “dependent files.” ) 
Each infile is separated from the next by a space. 


4, Type a number sign (#) if you want to add a comment to any line 
in a MAKE description filee MAKE ignores any text between the 
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number sign and the next new-line character. For example, you 
might want to add a comment as shown below: 


UPDATE .EXE: UPDATE.C GETINPUT.C FINDREC.C #UPDATE ROUTINE 


5. If any of the infiles have changed, type the command you want to 
carry out. In this example, assume that you want to recompile and 
relink all of the infiles. The resulting description file would look 
like this: 


UPDATE .EXE: UPDATE.C GETINPUT.C FINDREC.C #UPDATE ROUTINE 
QCL UPDATE.C GETINPUT.C FINDREC.C 


If you want to add a comment before or after the command line, 
the comment must appear in column 1, as shown below: 


UPDATE .EXE: UPDATE.C GETINPUT.C FINDREC.C # UPDATE ROUTINE 
# RECOMPILE AND RELINK 
QCL UPDATE.C GETINPUT.C FINDREC.C 


6. Save the description file and exit your text editor. Then type 
MAKE 


followed by the name of the description file and press ENTER. In 
this example, you would type 


MAKE UPDATE 


7. MAKE compares the last-modification dates of each of the infiles 
to the date of the outfile. If all of the infile dates are earlier than 
the outfile date, MAKE does nothing. If any infile date is later 
than the outfile date, MAKE recognizes that the outfile is out of 
date with respect to that infile and, therefore, carries out the com- 
mand you have indicated. In this example, MAKE recompiles the 
source files and relinks the corresponding object files to recreate 
UPDATE . EXE. 


11.1.2 Description Blocks 


A description block has the following general form: 


outfile: [infile]... [# comment] 
[# comment] 

command 

[command] 
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The following list defines the parts of a description block: 


Field 
outfile 


infile 


command 


comment 


Note 


Meaning 


Name of the file to be updated; may include drive 
or path specifications. Only one outfile is allowed. 


Names of files that, when any are changed, cause 
outfile to be updated; may include drive or path 
specifications. At least one space must separate 
one infile name from another. If you have more 
infile names than can fit on one line, type a back- 
slash (\), press RETURN, and then continue typing 
names on the next line. If no znfile is given, then 
MAKE carries out the commands in the block 
automatically. 


Command to be carried out if outfile is out of date 
with respect to an infile. Commands can be pro- 
grams, batch commands, or DOS commands. You 
can give any number of commands, but each must 
begin on a new line and each must be preceded by 
at least one space or tab. 


A comment character (#) followed by one or more 
characters. MAKE ignores all characters that fol- 
low the comment character on the same line. So, if 
you want a comment to appear on the same line as 
outfile, you must place it after the infile name(s). 
If a comment appears on a line where a command 
is expected, the comment character must be the 
first character on the line; no leading spaces are 
allowed. 


One way to remember the MAKE description-file format is to think of 
it in terms of an “if-then” form: if an ouffile is out of date with respect 
to any infile, or if an outfile does not exist, then do commands. 


You can give any number of description blocks in a description file. A 
blank line must appear between the last line of one description block and 
the first line of the next description block. 
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When you start MAKE, it reads the line in the first description block that 
names the outfile and infiles and then checks the modification dates of 
those files. If the modification date for any infile is later than the modi- 
fication date for the outfile, if the outfile does not exist, or if no infiles are 
given, MAKE displays and executes the commands specified in the block. 
Otherwise, it skips to the next block, repeating this sequence for each 
block in the file. 


If MAKE cannot find an infile, outfile, or command, it displays a diagnos- 
tic message. If the missing file is an outfile,s MAKE continues running 
since, in many cases, the missing file is created by later commands. If the 
missing file is an infile or a command file, MAKE stops running. 


MAKE also stops running and displays an exit code if any command in a 
block returns an error. 


Since MAKE processes description blocks in their order of appearance in 
the description file, it is important that the description blocks appear in 
the order in which you want processing to proceed. 


= Example 


MOD1.OBJ: MOD1.C 
QCL /e MOD1.C 


MOD2.OBJ: MOD2.C 
QCL /e MOD2.C 


EXAMPLE.EXE: MOD1.OBJ MOD2.OBJ 
LINK MOD1+MOD2, EXAMPLE , EXAMPLE ; 


In the example above, the description blocks appear in the order in which 
the outfiles are updated or created. Thus, MAKE updates MOD1.OBJ 
and MOD2.OBJ (or creates them, if necessary) before it updates or creates 


EXAMPLE .EXE. After MAKE is run, any changes to the source files are 
reflected in EXAMPLE.EXE. 


11.2 Running MAKE 


mw Syntax 
MAKE [options] [macrodefinitions] filename 


If you are running MAKE on a hard-disk system, use the DOS CD com- 
mand to make the current directory that directory which contains the 
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description file and the files you are working with. If you are running on a 
floppy-disk system, place your working copy of the Libraries #1 distribu- 
tion disk in drive A and the disk containing the description file and the 
files you are working with in drive B. 


The MAKE command line allows you to give information in addition to 
the name of the description file. The following list describes the informa- 
tion you can give on the MAKE command line: 


Field 


options 
macrodefinitions 


filename 


Meaning 


One or more MAKE options. 
One or more MAKE macro definitions. 


The name of a MAKE description file. 
This is usually the name of the program 
being maintained, without an extension. If 
you are updating a program named 
PROGRAM.C that was created within the 
QuickC environment, filename would be 
PROGRAM. MAK. 


The following list describes each option available with MAKE and how 
that option affects MAKE: 


Option 
/D 


/I 


/N 


/S 


/X filename 
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Action 


Displays the last modification date of each file as 
the file is scanned. 


Ignores exit codes (also called return or “error- 
level” codes) returned by programs that are called 
from the MAKE description file. 


“No-execution” mode: displays commands in the 
description file but does not execute these com- 
mands. This option is useful if you are > debugging a 


MAKE description file. 


“Silent” mode: does not display lines as they are 
executed. 


Redirects error messages from MAKE or any of 
the programs run by MAKE to the given file. If 
filename is a dash (-), error messages are redirected 
to the standard output device. If this option is not 
given, error messages are sent to the standard 
error-output device. 


Automating Program Development with MAKE 


11.3. Using Macro Definitions with MAKE 


One way to simplify definition files is to use macros. A “macro” is simply a 
name that you can substitute for other text in a MAKE description file. 
To change the text that the name represents, you only need to change it in 
the macro definition. The text is automatically updated everywhere else 
that the name is used. 


You might want to use macros 


e As the base names of source, object, and executable files under 
development. If the program name changes, you can change the 
base name in the macro definition; then the base name is changed 
automatically for the source, object, and executable files given in 
the description file. 


e Tospecify a particular set of options for a command such as QCL 
or LINK. If the options change, you can change them throughout 
the description file simply by changing the macro definition. 


11.3.1 Defining and Specifying Macros 
A macro definition has the following general form: 
name= text 


After you define a macro, you can use it in the description file as shown 
below: 


$(name) 


Wherever the pattern $(name) appears in the description file, that pattern 
is replaced by text. The name is converted to uppercase; for example, the 
names flags and FLAGS are equivalent. If you define a macro name but 
leave text blank, or if you use a macro name that has not been defined, teat 
will be a null string. 


For name, you can also use any environment variable that is defined in the 
current environment. For example, if the environment variable PATH is 
defined in the current environment, the value of PATH replaces any 
occurrences of $ (PATH) in the description file. (Note that using this 
macro does not redefine the value of PATH in the current environment.) 
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You can give macro definitions in either of the following places: 


e Before any description block in a MAKE description file. Each 
macro definition must appear on a separate line. Any tab or space 
characters between name and the equal sign (=), or between the 
equal sign and tezt, are ignored. Any other tabs or spaces are con- 
sidered part of tezt. 


e On the MAKE command line. 


To include tab or space characters in a macro definition on the command 
line, enclose the entire definition in double quotation marks (" "). 


If the same name is defined in more than one place, the following order of 
precedence applies: 


1. Command-line definition 

2. Description-file definition 

3. Environment definition 
For example, if PATH is defined in the DOS environment and in a 
description file. MAKE uses the definition in the description file. If it is 


also defined on the MAKE command line, the command-line definition 
supersedes the other two definitions. 


m Example 


Assume the existence of the following MAKE description file named 
COMPILE: 


base=ABC 
debug="/Zi" 


$ (base) . EXE: $ (base) .C 
QCL $(debug) $ (base) .C 


In this description file, macro definitions are given for the names base 
and debug. 


The base macro defines the base name of the object and executable files 
being maintained. MAKE replaces each occurrence of $ (base) with the 
text ABC. If the program name changes, you would only have to replace 
ABC in the macro definition with the new program name to change the 
base name of the two files. 
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The debug macro tells the QCL command to create an executable file for 
the QuickC or CodeView debugger. 


If you want to override one of the macro values in this description file, you 
can give a new macro definition on the MAKE command line, as shown in 
the following example: 


MAKE base=DEF compile 


This command-line definition of base overrides the definition of base in 
the description file. As a result, base is replaced with the text DEF 
instead of ABC. 


If you do not want to create an executable file containing debugging infor- 
mation, you could run MAKE with the following command line: 


MAKE debug= compile 


Because macros defined on the command line have higher precedence than 
those defined in the description file, MAKE uses the command-line defi- 
nition (a null string; note the white space between the equal sign and the 
MAKE description-file name) for the $ (debug) macro. As a result, the 
/ Zi switch does not appear on the QCL command line, and the executable 
file that is created does not include the information needed for debugging. 


11.3.2 Using Macros within Macro Definitions 


Macros can be used within macro definitions. For example, you could 
have the following macro definition in a MAKE description file named 
PICTURE: 

LIBS=s (DLIB) \MLIBCE.LIB $ (DLIB)\GRAPHICS.LIB 


You could then run MAKE and specify the definition for the macro 
named $(DLIB) on the command line, as shown in the following exam- 


ple: 

MAKE DLIB=C:\LIB PICTURE 

In this case, every occurrence of the macro $(DLIB) in the description 
file would be expanded to C:\LIB; consequently, the definition of the 

LIBS macro in the description file would be expanded to the following: 


LIBS=C:\LIB\MLIBCE.LIB C:\LIB\GRAPHICS.LIB 
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Be careful to avoid infinitely recursive macros such as the following: 


QW > 
et 


In the example above, if the macro $(B) has not been defined before the 
A = $(B) line, all of the other macros will be undefined as well. 


11.3.3 Using Special Macros 


MAKE recognizes the following special macro names and automatically 
substitutes the corresponding text for each: 


Name Text Substituted 
$ « Base name of the outfile 
$@ Complete outfile name 


$ oo Complete list of infiles 


mg Example 


 TEST.EXE: MOD1.OBJ MOD2.OBJ MOD3.OBJ 


LINK $«**, $@: 
Sx 


In the LINK command in the example above, $«* represents all of the 
infiles that correspond to the outfile TEST.EXE, and $@ specifies the 
complete name of TEST.EXE as the executable-file name on the LINK 
command line. The final line uses $% to specify the base name of 

TEST .EXE-that is, TEST—as the next command to be carried out. There- 
fore, this example is equivalent to the following: 


TEST:EXE: MOD1.OBJ MOD2.OBJ MOD3.OBJ 
LINK MOD1.OBJ MOD2.OBJ MOD3.OBJ, TEST.EXE; 
TEST 


11.4 Defining Inference Rules 


Often you use MAKE to update one type of file when a file of another 
type is changed. For example, you often use MAKE to update object files 
when source files change, or to update executable files or libraries when 
source or object files change. 
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In cases such as these, you can define “inference rules” for MAKE to fol- 
low. These rules allow you to give a single MAKE command to convert all 
outfiles with a given extension to files with a different extension. For exam- 
ple, you can use inference rules to specify a single QCL command that 
changes any source file (which has an extension of .C) to an executable file 
(which has an extension of .EXE). Since MAKE looks for an applicable 
inference rule whenever no commands appear in a description block, you 
would not have to include the QCL command in all blocks in which you 
compile and link a file. 


Inference rules have the following general form: 


-ineztension.outextension : 
command 
[command] 


In this format, command specifies one of the commands that you must use 
to convert files with extension ineztension to files with extension 
outeztension. Using the earlier example of converting source files to exe- 
cutable files, you could define the following inference rule to compile and 
link all source files in the current directory to create object files: 


.C.EXE: 
QCL $#.C 


Giving an inference rule without a command has the effect of canceling an 
inference rule that has already been defined. 


If MAKE finds a description block without any commands, it looks for an 

inference rule that matches both the outfile extension and the infile exten- 

sion. If it finds such a rule. MAKE carries out any commands that are 
given in the rule. 


You can include inference rules in either of the following places: 


e Ina MAKE description file. 


e Ina file named TOOLS.INI. This file is known as the “tools ini- 
tialization file.” A line beginning with the tag [make] must appear 
before any dependency rules in TOOLS.INI. 

MAKE searches for dependency rules in the following order: 


1. In the current description file. 
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2. Inthe TOOLS.INI file. MAKE looks for TOOLS.INI in the 
current drive and directory. If it cannot find this file, then MAKE 
looks for TOOLS.INI in the directory indicated by the INIT 
environment variable. If MAKE finds TOOLS.INI, it looks 
through the file for a line beginning with the tag [make]. It applies 
any appropriate inference rules following this line. 


m Example 
Assume the following entry in the TOOLS.INI file: 


[make] 
-OBJ.LIB: 
LIB TEST.LIB +$*.OBJ: 


Now assume the following description file: 


EXAMPLE1.LIB: EXAMPLE1.OBJ 


EXAMPLE2.EXE: EXAMPLE2.OBJ 
LINK /CO EXAMPLE2,,,LIBV3.LIB 


The TOOLS.INI file defines an inference rule that executes the LIB com- 
mand in the description file to update a library whenever a change is made 
in the corresponding object file. The file name in the inference rule is 
specified with the special macro name $* so that the rule applies to any 
file with the .OBJ extension. 


When MAKE encounters a line containing an outfile and one or more 
infiles, it first looks for commands on the next line. If it does not find any 
commands, MAKE checks for a rule that may apply; in this case, it finds 
the rule defined in TOOLS.INI. MAKE applies the rule, replacing the 
$* macro with EXAMPLE1 when it executes the command; consequently, 
the LIB command becomes 


LIB TEST.LIB +EXAMPLE1.OBJ; 


When MAKE reaches the line containing the EXAMPLE2.EXE outfile, it 
does not search for a dependency rule, since a command is explicitly given 
for this outfile/infile relationship. Thus, in this case, MAKE links the 
object file EXAMPLE2.OBJ with the LIBV3.LIB library to create an exe- 
cutable file instead of adding EXAMPLE2.OBJ tothe TEST.LIB library. 
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11.5 Using .MAK Files 


If you create a program list for a program within the QuickC environment, 
QuickC automatically creates a MAKE description file for that program. 
The description file has the same base name as the program, with the 
extension .MAK. The description file allows QuickC to recompile and 
relink all of the modules that make up the program if any module in the 
program, or any include file specified in a program module, has been 
updated. 


11.5.1 Using .MAK Files with MAKE 


With minor changes, you can use the MAKE utility with a .MAK file to 
update a program outside the QuickC environment. Recall that a library 
with a .LIB extension must be present when you create a program outside 
of QuickC. If a Quick library was loaded in the QuickC environment at the 
time you compiled the program, the .MAK file will contain a comment 
line indicating the name of the Quick library. 


Use this procedure when you update a program outside of QuickC: 


1. Make a copy of the .MAK file under a different name so that 
QuickC can continue using the original. 


2. Edit this copy, substituting the name of the appropriate stand- 
alone library name for the comment line that shows where the 
library name should go. 


3. Run MAKE and give the name of the edited .MAK file for the 
program as input. MAKE automatically recompiles and relinks 
the program, which can be loaded into the the QuickC environ- 
ment as usual. 


11.5.2 Include File Dependencies 


During program development, you will often centralize definitions of con- 
stants, macros, and external variables in an include file, then use the 

# include directive to include this code in different program modules. 
Using this mechanism, you need only update the common code contained 
in the include file, since the modules that include copies of the common 
code are automatically updated when you recompile them. 


To make sure that a program is updated automatically when any of its 
include files has been changed, be sure to give include files among the 
infiles in the MAK file. Although the QuickC compiler does not place 
include files in a .MAK file automatically, it does preserve any include 
files that you place in the .MAK file by using an editor. 
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When you load a program list in the QuickC environment by using the Set 
Program List command, any include files you have given in the .MAK file 
are included in the program list. The QuickC compiler uses the include file 
in the same way as any other file in the program list: if the include file has 
been updated since the last time the program was compiled, it recompiles 

the program. 


mg Example 


Assume that each module of a program named Lexer has an include file 
named globals.h, which resides in the \INCLUDE directory. Assume 
also that the first few lines of the lexer.mak file are 


# 


# Program: Lexer 
qcl -c -WO -Zq -AM $#.c 
lexer.obj : C:\SRC\lexer.c 


gettoken.obj : C:\SRC\gettoken.c 


You can change the lexer.mak file as shown below to make sure that 
Lexer is updated whenever globals.h has been updated: 


# 


# Program: Lexer 
qcl -c -WO -Zq -AM Sk.c 
lexer.obj} : C:\SRC\lexer.c C:\INCLUDE\globals.h 


gettoken.obj : C:\SRC\gettoken.c C:\INCLUDE\globals.h 


11.5.3 Specifying Linker Options 


When the QuickC compiler compiles a program with a program list, it 
first compiles the modules in the program list, then links the resulting 
object files. You can control the linking process by specifying linker condi- 
tions in the .MAK file that contains the program list. Simply define a 
macro named LDFLAGS as shown below: 
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LDFLAGS= link-opt ... 


The LDFLAGS macro is automatically included on the LINK command 
line in the .MAK file. Your definition must follow the rules outlined in 
Section 11.3.1. 


The LINK options that you specify are used each time you recompile and 
relink the modules in the program list; they remain in use until you change 
the value of LDFLAGS in the .MAK file. 
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You can gain greater control over how your program uses memory by 
specifying the memory model for the program. Ordinarily, you do not need 
to specify a memory model except in the following cases: 


e <A program compiled within the QuickC environment has more 
than 64K of static data. 


e A program compiled with the QCL command has more than 64I¢ 
of code or more than 64K of static data. 


In these cases, you have the following options: 


1. If you are compiling with the QCL command, you can specify one 
of the other standard memory models (medium, compact, or large) 
using one of the /A options. 


2. You can create a mixed-model program using the near and far 
keywords. 


3. You can combine method 2 with method 1. 


B.1 Near and Far Addressing 


The terms “near” and “far” are crucial to understanding the concept of 
memory models. These terms indicate how data can be accessed in the seg- 
mented architecture of the 8086 family of microprocessors (8086, 80186, 
and 80286). 


DOS loads the code and data allocated by your program into “segments” 
in physical memory. Each segment is up to 64K long. Since separate seg- 
ments are always allocated for the program code and data, the minimum 
number of segments allocated for a program is two. These two segments, 
required for every program, are called the default segments. The small 
memory model uses only the two default segments. The other memory 
models discussed in this chapter allow more than one code segment per 
program, or more than one data segment per program, or both. 


In the 8086 family of microprocessors, all memory addresses consist of two 
parts: 


1. A 16-bit number that represents the base address of a memory 
segment 


2. Another 16-bit number that gives an offset within that segment 
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The architecture of the 8086 microprocessor is such that code can be 
accessed within the default code or data segment by using just the 16-bit 
offset value. This is possible because the segment addresses for the default 
segments are always known. This 16-bit offset value is called a “near 
address”; it can be accessed with a “near pointer.” Since only 16-bit arith- 
metic is required to access any near item, near references to code or data 
are smaller and more efficient. 


When data or code lie outside the default segments, the address must use 
both the segment and offset values. Such addresses are called “far ad- 
dresses” ; they can be accessed by using “far pointers” in a C program. 
Accessing far data or code items is more expensive in terms of program 
speed and size, but using them enables your programs to address all 
memory, rather than just a 64I< piece. 


The rest of this chapter deals with the various methods you can use to 
control whether your program makes near or far calls to access code 
or data. 


B.2 Using the Standard Memory Models 


The libraries created by the SETUP program support four standard 
memory models. Using the standard memory models is the simplest way to 
control how your program accesses code and data in memory. 


When you use the standard memory models, the compiler handles library 
support for you. The library corresponding to the memory model you 
specify is used automatically. Each memory model has its own library. 


The advantage of using standard models for your programs is simplicity. 
In the standard models, memory management is specified by compiler 
options; since the standard models do not require the use of extended key- 
words, they are the best way to write code that can be ported to other sys- 
tems (particularly systems that do not use segmented architectures). 


The disadvantage of using standard memory models exclusively is that 
they may not produce the most efficient code. For example, if you have an 
otherwise medium-model program containing a large array that pushes the 
total data size for your program over the 64K limit for medium model, it 
may be to your advantage to declare the one array with the far keyword, 
while keeping the rest of the program medium model, as opposed to using 
the standard compact memory model for the entire program. For max- . 
imum flexibility and control over how your program uses memory, you can 
combine the standard-memory-model method with the near and far key- 
words, described in Section B.3. 


274 


Working with QuickC Memory Models 


The /A option for QCL is used to specify one of the four standard 
memory models (small, medium, compact, or large) at compile time. These 
memory-model options are discussed in the next four sections. 


Note 


In the following sections, which describe the different memory-model 
addressing conventions, it is important to keep in mind two common 
features of all five models: 


1. No szngle source module can generate 64K or more of code. 


2. No stngle data item can exceed 64K. 


B.2.1 Creating Small-Model Programs 


= Option 
/AS 


The small-model option tells the compiler to create a program that occu- 
pies the two default segments—one for code and one for data. 


Small-model programs are typically C programs that are short or have a 
limited purpose. Since code and data for these programs are each limited 
to 64K, the total size of a small-model program can never exceed 128K. 
Most programs fit easily into this model. 


By default, both code and data items in small-model programs are ac- 
cessed with near addresses. You can override the defaults for data and 
code by using the far keyword. 

The QCL command creates small-model programs automatically if you do 
not specify a memory model. The /AS option is provided for complete- 
ness; you never need give it explicitly. 


Figure B.1 illustrates how memory is set up for the small memory model. 
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High memory 


’ NEE RAT TT IRE 
ee ~— Unallocated memory used for dynamic allocation 


STACK ~— Local data 
Scomaon —— Uninitialized global and static data 
CONST : —— Compiler-generated read-only data 


_DATA —~ Default data segment: initialized global and static data 


NULL f ~—— Checks for null-pointer assignment 


_ TEXT ~~ Code segment for all modules 


Low memory 


Figure B.1 Memory Map for Small Memory Model 


B.2.2 Creating Medium-Model Programs 


m= Option 
/AM 


The medium-model option provides a single segment for program data and 
multiple segments for program code. Each source module is given its own 
code segment. 


Medium-model programs are typically C programs that have a large num- 
ber of program statements (more than 64K of code), but a relatively small 
amount of data (less than 64K). Program code can occupy any amount of 
space and is given as many segments as needed; total program data cannot 
be greater than 64K. The medium model provides a useful trade-off 
between speed and space, since most programs refer more frequently to 
data items than to code. 


Since programs compiled within the QuickC environment always use the 
medium memory model, you should give this option in cases where you use 
the QCL command to compile a module for use within the QuickC envi- 
ronment. 
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Figure B.2 illustrates how memory is set up for the medium memory 
model. 


High memory 


Heap ~— Unallocated memory used for dynamic allocation 


STACK f — Local data 
Seouion f — Uninitialized global and static data 
CONST f —— Compiler-generated read-only data 


_DATA A —~ Default data segment: initialized global and static data 
NULL j —— Checks for null-pointer assignment 


EE CEE 
module_TEXT ~— One code segment per module 


Low memory 


Figure B.2 Memory Map for Medium Memory Model 
B.2.3 Creating Compact-Model Programs 


= Option 
/AC 


The compact-model option directs the compiler to allow multiple segments 
for program data, but only one segment for the program code. 


Compact-model programs are typically C programs that have a large 
amount of data, but a relatively small number of program statements. 
Program data can occupy any amount of space and are given as many seg- 
ments as needed. 


By default, code items in compact-model programs are accessed with near 
addresses, and data items are accessed with far addresses. You can over- 
ride the default by using the near keyword for data and the far keyword 
for code. 
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Figure B.3 illustrates how memory is set up for the compact memory 
model. 


High memory 


~~ Unallocated far memory used for dynamic allocation 


~— Unallocated near memory used for dynamic allocation 


— Local data 

~=— Uninitialized global and static data 

—— Compiler-generated read-only data 

—~— Default data segment: initialized global and static data 


~— Checks for null-pointer assignment 


~— Initialized and uninitialized global and static far data 


~— Code segment for all modules 


Low memory 


Figure B.3 Memory Map for Compact Memory Model 
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Note 


Note that in medium and compact models, NULL must be used care- 
fully in certain situations. NULL actually represents a null data 
pointer. In memory models where code and data pointers are the same 
size, it can be used with either. However, in memory models where 
code and data pointers are different sizes, this is not the case. Consider 
the following example: 


void funcl (char *#dp) 
{ 


} 
void func2(char (*fp) (void) ) 


} 
main () 


funci (NULL) ; 
func2 (NULL) ; 
} 


This example passes a 16-bit pointer to both funcl and func2 if 
compiled in medium model, and a 32-bit pointer to both funcl and 
func2 if compiled in compact model, unless prototypes are added to 
the beginning of the program to indicate the types, or an explicit cast 
is used on the argument to funcl (compact model) or func2 
(medium model). 


B.2.4 Creating Large-Model Programs 


= Option 
/AL 


The large-model option allows the compiler to create multiple segments, as 
needed, for both code and data. 
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Large-model programs are typically very large C programs that use a large 
amount of data storage during normal processing. 


By default, both code and data items in large-model programs are accessed 
with far addresses. You can override the default by using the near key- 
word for data and code. 


Figure B.4 illustrates how memory is set up for the large memory model. 


High memory 


~~ Unallocated far memory used for dynamic allocation 


~— Uninitialized global and static data 
—— Compiler-generated read-only data 
— Default data segment: initialized global and static data 


—— Checks for null-pointer assignment 


Le 
Data segments i —— Initialized and uninitialized global and static far data 


{oa 
module_TEXT ~~ One code segment per module 


Low memory 


Figure B.4 Memory Map for Large Memory Model 


B.3 Using the near and far Keywords 


One limitation of the predefined memory-model structure is that, when 
you change memory models, all data and code address sizes are subject to 
change. However, the Microsoft QuickC Compiler lets you override the 
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default addressing convention for a given memory model and access items 
with a near or far pointer. This is done with the near and far keywords. 
These special type modifiers can be used with a standard memory model 
to overcome addressing limitations for particular data or code items, or 
to optimize access to these items, without changing the addressing con- 
ventions for the program as a whole. Table B.1 explains how the use of 
these keywords affects the addressing of code or data, or pointers to code 


or data. 


Table B.1 


Addressing of Code and Data Declared with near and far 


Keyword Data 


Resides in default 
data segment; 
referenced with 16-bit 


addresses (pointers to 
data are 16 bits) 


near 


far May be anywhere in 
memory—not 
assumed to reside in 
current data segment; 
referenced with 32-bit 
addresses (pointers to 
data are 32 bits) 


Note 


Pointer 


Function Arithmetic 


Assumed to be in Uses 16 bits 
current code 
segment; 
referenced with 
16-bit addresses 
pose to 
unctions are 16 
bits) 
Not assumed to be 
in current code 
segment; 
referenced with 
32-bit address 
ppomvers to 
unctions are 32 
bits 


Uses 16 bits 


The near and far keywords are not a standard part of the C language; 
they are meaningful only for systems that use a segmented architecture 
similar to that of the 8086 microprocessors. Keep this in mind if you 
want your code to be ported to other systems. 


In the Microsoft QuickC Compiler, the words near and far are C key- 
words by default. To treat these keywords as ordinary identifiers, you 


must do one of the following: 
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e For programs compiled within the QuickC environment, compile 
with the Language Extensions option turned off. 


e For programs compiled with the QCL command, give the /Za 
option at compile time. 


These options are useful if you are compiling programs with compilers in 
which near and far are not keywords—for instance, if you are porting a 
program in which one of these words is used as a label. See Section 8.1.4.6, 
“Using Microsoft Extensions to C: the Language Extensions Option,” for 
further information about the use and effects of the Language Extensions 
and /Za options. 


B.3.1 Library Support for near and far 


When using the near and far keywords to modify addressing conventions 
for particular items, you can usually use one of the standard libraries 
(small, compact, medium, or large) with your program. However, you must 
use care when calling library routines. In general, you cannot pass far 
pointers, or the addresses of far data items, to a small-model library rou- 
tine. (Some exceptions to this statement are the library routines halloc 
and hfree, and the printf family of functions.) Of course, you can always 


pass the value of a far item to a small-model library routine. For example: 


long far time_val; 


time (&time_val); /* Illegal */ 
printf ("%ld\n", time_val); /* Legal */ 


If you use the near or far keyword, it is strongly recommended that you 
use function prototypes with argument-type lists to ensure that all pointer 
arguments are passed to functions correctly. See Section B.3.4, “Pointer 
Conversions,” for more information. 


B.3.2 Declaring Data with near and far 


The near and far keywords modify either objects or pointers to objects. 
When using them to declare data or code (or pointers to data or code), 
keep the following rules in mind: 


e The keyword always modifies the object or pointer immediately to 
its right. In complex declarators, think of the far keyword and the 
item immediately to its right as being a single unit. For example, 
in the declarator 


char fars* «xp; 
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p is a pointer (whose size depends on the memory model specified) 
to a far pointer to char. See the Microsoft CLanguage Reference 
for complete rules for using special keywords in complex declara- 
tions. 


e If the item immediately to the right of the keyword is an identifier, 
the keyword determines whether the item will be allocated in the 
default data segment (near) or a separate data segment (far). For 
example, 


char near a; 
allocates a as an item of type char with a near address. 


e If the item immediately to the right of the keyword is a pointer, 
the keyword determines whether the pointer will hold a near ad- 
dress (16 bits) or a far address (32 bits). For example, 


char far *p; 
allocates p as a far pointer (32 bits) to an item of type char. 


e The far keyword cannot be used to declare data items in programs 
that will be run within the QuickC environment. However, it can 
be used to declare pointers to data items. For example, 


int far item: 
is illegal for in-memory programs, but 
int far xitem: 


is legal. 


=m Examples 


The examples in this section show data declarations using the near and 
far keywords. 


char a[3000]; 7* small-model program */ 
char far b[30000]; 


The first declaration in the example above allocates the array a in the 
default data segment. By contrast, the array b in the second declaration 
may be allocated in any far data segment. Since these declarations appear 
in a small-model program, array a probably represents frequently used 
data that were deliberately placed in the default segment for fast access. 
Array b probably represents seldom-used data that might make the de- 
fault data segment exceed 64K and force the programmer to use a larger 
memory model if the array were not declared with the far keyword. The 
second declaration uses a large array because it is more likely that a pro- 
grammer would want to specify the address allocation size for items of 
substantial size. 
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char a[3000]; /* large-model program +/ 
char near b[3000] ; 


In the example above, access speed would probably not be critical for 
array a. Even though it may or may not be allocated within the default 
data segment, it is always referenced with a 32-bit address. Array b is 
explicitly allocated near to improve speed of access in this memory model 


(large). 


char *pa; /* small-model program +/ 
char far *pb; 


The pointer pa is declared as a near pointer to an item of type char in 
the example above. The pointer is near by default since the example 
appears in a small-model program. By contrast, pb is allocated as a far 
pointer to an item of type char; pb could be used to point to, and step 
through, an array of characters stored in a segment other than the default 
data segment. For example, pa might be used to point to array ain the 
first example, while pb might be used to point to array b. 


char far * *pa; /* small-model program */ 
char far * *pa; /* large-model program */ 


The pointer declarations in the example above illustrate the interaction 
between the memory model chosen and the near and far keywords. 
Although the declarations for pa are identical, in a small-model program 
pa is declared as a near pointer to an array of far pointers to type char, 
while in a large-model program, pa is declared as a far pointer to an array 
of far pointers to type char. 


char far * near *pb; /* any model +*/ 
char far * far *pb; 


In the first declaration in the example above, pb is declared as a near 
pointer to an array of far pointers to type char; in the second declaration, 
pb is declared as a far pointer to an array of far pointers to type char. 
Note that, in this example, the far and near keywords override the 
model-specific addressing conventions shown in the example preceding the 
example above; the declarations for pb would have the same effect, 
regardless of the memory model. 
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B.3.3 Declaring Functions 


with the near and far Keywords 


The rules for using the near and far keywords for functions are similar to 
those for using them with data, as listed below: 


The keyword always modifies the function or pointer immediately 
to its right. See Section 4.3.3, “Declarators with Special Key- 
words,” of the Microsoft C Language Reference for more informa- 
tion about rules for evaluating complex declarations. 


If the item immediately to the right of the keyword is a function, 
then the keyword determines whether the function will be allocated 
as near or far. For example, 


char far fun( ); 
defines fun as a function called with a 32-bit address and return- 
ing type char. 


If the item immediately to the right of the keyword is a pointer to 
a function, then the keyword determines whether the function will 
be called using a near (16-bit) or far (32-bit) address. For example, 


char (far * pfun)( ); 


defines pfun as a far pointer (32 bits) to a function returning type 
char. 


Function declarations must match function definitions. 


=” Examples 


void char far fun(void); /* small model +*/ 
void char far fun (void) 


} 


In the example above, fun is declared as a function returning type char. 
The far keyword in the declaration means that fun must be called with a 
32-bit call. 
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static char far * near fun( ); /* large model +/ 
static char far * near fun( ) 


} 
In the large-model example above, fun is declared as a near function that 
returns a far pointer to type char. Such a function might be seen in a 
large-model program as a helper routine that is used frequently, but only 
by the routines in its own module. Since all routines in a given module 
share the same code segment, the function could always be accessed with a 


near call. However, you could not pass a pointer to fun as an argument 
to another function outside the module in which fun was declared. 


void far *«fun(void); /* small model «/ 
void (far * pfun) ( ) = fun; 


The small-model example above declares pfun as a far pointer to a func- 
tion that has a void return type, and then assigns the address of fun to 
pfun. In fact, pfun could be used to point to any function accessed with 
a far call. Note that if the function pointed to by pfun has not been 
declared with the far keyword, or if it is not far by default, then calling 
that function through pfun would cause the program to fail. 


double far * (far fun) ( ); /* compact model +s/ 
double far *« (far *pfun)( ) = fun; 


The final example above declares pfun as a far pointer to a function that 
returns a far pointer to type double, and then assigns the address of fun | 
to pfun. This might be used in a compact-model program for a function 
that is not used frequently and thus does not need to be in the default 
code segment. Both the function and the pointer to the function must be 
declared with the far keyword. 


B.3.4 Pointer Conversions 
Passing pointers as arguments to functions may cause automatic conver- 


sions in the size of the pointer argument, since passing a pointer to a func- 
tion forces the pointer size to the larger of the following two sizes: 
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e The default pointer size for that type, as defined by the memory 
model used during compilation. 


For example, in medium-model programs, data pointer arguments 
are near by default and code pointer arguments are far by default. 


e The type of the argument. 


If a function prototype with argument types is given, the compiler per- 
forms type checking and enforces the conversion of actual arguments to 
the declared type of the corresponding formal argument. However, if no 
declaration is present or the argument-type list is empty, the compiler will 
convert pointer arguments automatically to either the default type or the 
type of the argument, whichever is largest. To avoid mismatched argu- 
ments, you should always use a prototype with the argument types. 


= Examples 


/* This program produces unexpected results in compact- or 
** large-model programs. 


*/ 
main( ) 


{ 

int near *x: 
char far ty; 
int z= 1: 


test_fun(x, y, Zz); /* x is coerced to far pointer «/ 


E 


int test_fun(ptrl, ptr2, a) 
int near *ptrl; 
char far *ptr2; 
int a; 


at 
printf ("Value of a = %d\n", a); 
5 


If the preceding example is compiled as a small-model program (with /AS 
option on the QCL command line) or medium-model program (with no 
memory-model options or the /AM option on the QCL command line), 
the size of pointer argument x is 16 bits, the size of pointer argument y 
is 32 bits, and the value printed for a is 1. However, if the preceding 
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example is compiled with the /AC or /AL option, both x and y are 
automatically converted to far pointers when they are passed to 
test_fun. Since ptr1, the first parameter of test_fun, is defined as a 
near pointer argument, it takes only 16 bits of the 32 bits passed to it. 
The next parameter, ptr2, takes the remaining 16 bits passed to ptr1, 
plus 16 bits of the 32 bits passed to it. Finally, the third parameter, a, 
takes the leftover 16 bits from ptr2, instead of the value of z in the 
main function. This shifting process does not generate an error message, 
since both the function call and the function definition are legal, but in 
this case the program does not work as intended, since the value assigned 
to a is not the value intended. 


To pass ptri as a near pointer, you should include a forward declaration 
that specifically declares this argument for test_fun as a near pointer, 
as shown below: 


/* First, declare test_fun so the compiler knows in advance 
** about the near pointer argument: 
* 


int test_fun(int near+, char far *, int); 


main( ) 


int near *x: 
char far sy; 
int z= 1: 


test_fun(x, y, 2); /* now, x will not be coerced 
** to a far pointer; it will be 
**x passed as a near pointer, 
** no matter what memory 
**x model is used 
*/ 

} 


int test_fun(ptrl, ptr2, a) 
int near *ptrl; 
char far x*ptr2; 
int a; 


{ 
printf ("Value of a = %d\n", a); 
} 


Note that it would not be sufficient to reverse the definition order for 
test_fun and main in the first example to avoid pointer coercions; the 
pointer arguments must be declared in a forward declaration, as in the 
second example. 
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B.4 Setting the Data Threshold 


= Option 
/Gt[ number] 


By default, the compiler allocates all static and global data items within 
the default data segment in the small and medium memory models. In 
compact- and large-model programs, only inztzalized static and global data 
items are assigned to the default data segment. The /Gt option causes all 
data items whose size is greater than or equal to number bytes to be allo- 
cated to a new data segment. When number is specified, it must follow the 
/Gt option immediately, with no intervening spaces. When number is 
omitted, the default threshold value is 256. When the /Gt option is omit- 
ted, the default threshold value is 32,767. 


You can use the /Gt option only with compact- and large-model pro- 
grams, since small- and medium-model programs have only one data seg- 
ment. The option is particularly useful with programs that have more 
than 64K of initialized static and global data in small data items. 


B.5 Naming the Text Segment 


= Option 
/NT textsegment 


A “segment” is a contiguous block of binary information Ca or data) 
produced by the Microsoft QuickC Compiler. Every module (that is, every 
object file produced by the compiler) has at least two segments: a text seg- 
ment containing the program instructions, and a data segment containing 
the program data. 


Each segment in every module has a name. The linker uses this name to 
define the order in which the segments of the program appear in memory 
when loaded for execution. (Note that the segments in the group named 
DGROUP are an exception.) 


Text- and data-segment names are normally created by the QuickC com- 
piler. In medium-model programs, the text from each module is placed in a 
separate segment with a distinct name, formed by using the module base 
name along with the suffix TEXT. The data segment is named _DATA. 
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You can override the default text-segment name used by the QuickC com- 
piler (thus overriding the default loading order) by using the /NT (for 
“name text”) option. This option gives the text segment a new name in 
each module being compiled. 


The textsegment argument used with the /NT option can be any combina- 


tion of letters and digits. The space between /NT and teztsegment is 
optional. 
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Mixed-language programming is the process of creating programs from 
two or more source languages. This capability allows you to combine the 
unique strengths of Microsofte BASIC, C, FORTRAN, Pascal, and the 
Macro Assembler (MASM). Any one of these languages (in their recent 
versions) can call any of the others. Virtually all of the routines from each 
of these extensive language libraries are available to a mixed-language 
program. 


For example, mixed-language programming helps you effectively use 
MASM. You can develop the majority of your program quickly with 
Microsoft C or FORTRAN, then call MASM for those few routines that 
are executed many times and must run with utmost speed. 


Mixed-language programming also facilitates the transition from one 
language to another. For example, you may have a large FORTRAN pro- 
gram that you are converting to C. You can replace your FORTRAN sub- 
routines, one by one, with corresponding C functions. C-generated code 
can come on line as soon as each function is written. 


Finally, mixed-language programming is particularly valuable if you are 
marketing your own libraries. With the techniques presented here, you can 
produce libraries for any of the languages mentioned above, often with lit- 
tle change. 


The details of mixed-language programming for the other high-level 
Microsoft languages are contained in the Microsoft Mired-Lanquage Pro- 
gramming Guide. This manual is included with Microsoft FORTRAN (Ver- 
sion 4.0 or later), Microsoft Macro Assembler ee 5.0 or ner icro- 
soft Pascal (Version 3.3 or later), and Microsoft C (Version 5.0 or later). 


This appendix focuses on the concepts, syntax, and programming methods 
necessary to write assembly-language routines usable with a C program. 
Refer to the Microsoft Mized-Language Programming Guide for detailed 
information for the high-level language interfaces. 
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™ Definitions 


The notational conventions used in this appendix are consistent with the 
conventions described in the user’s guide for each Microsoft language. 
However, the following terms are used in specialized ways: 


Term Definition 


Routine Any function, subprogram, subroutine, or pro- 
cedure that can be called from another language. 


The concept is similar to that of a procedure in 
assembly language; however, the term “routine” is 
used in most contexts to avoid confusion with the 
Pascal keyword procedure. 


Parameter A piece of data passed directly between two rou- 
tines. (External data are shared by all routines, 
but cannot be said to be passed.) 


Although elsewhere the term “argument” is some- 

times used interchangeably with “parameter,” in 

this appendix “argument” is used to refer to the 

particular values or expressions that are given for 
_ parameters. 


Interface A method for providing effective communication 
between different formats. With high-level lan- 
guages, an interface is often established by some 
kind of formal declaration. 


Formal A formal parameter is a dummy parameter de- 

parameter clared in an interface statement or declaration. C 
uses parameter-type declarations rather than for- 
mal parameters. 


C.1 Writing the Assembly Procedure 


The Microsoft high-level languages all use roughly the same interface for 
procedure calls. This section describes the interface, which allows you to 
call assembly procedures by using the same methods as you do with Micro- 
soft compiler-generated code. Procedures written with these methods can 
be called recursively and can be effectively used with the Stack Trace 
feature of the Microsofte CodeViewe window-oriented debugger. 


The standard assembly-interface method consists of these steps: 
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Set up the procedure 

Enter the procedure 

Allocate local data (optional) 
Preserve register values 
Access parameters 

Return a value (optional) 


Exit the procedure 


Sections C.1.1—C.1.7 describe each of these steps. 


C.1.1 Setting Up the Procedure 


The linker cannot combine the assembly procedure with the calling pro- 
gram unless compatible segments are used and unless the procedure itself 
is declared properly. The following points may be helpful: 


Use the .MODEL directive at the beginning of the source file, if’ 
you have Version 5.0 of the Macro Assembler. This directive auto- 
matically causes the appropriate kind of returns to be generated 
(near for small or compact model, far otherwise). If you have a ver- 
sion of the assembler previous to 5.0, declare the procedure far (or 
near if the calling program is small- or compact-model QuickC). 


If you have Version 5.0 or later of the Microsoft Macro Assembler, 
use the simplified segment directives .CODE to declare the code 
segment and .DATA to declare the data segment. (Having a code 
segment is sufficient if you do not have data declarations.) If you 
are using an earlier version of the assembler, look up SEGMENT, 
GROUP, and ASSUME directives in Section C.4, “The Microsoft 
Segment Model.” 


The procedure label must be declared public with the PUBLIC 
directive. This declaration makes the procedure available to be 
called by other modules. Also, any data you want to make public 
to other modules must be declared as PUBLIC. 


Global data or procedures accessed by the routine must be declared 
EXTRN. The safest way to use EXTRN is to place the directive 
outside of any segment definition (however, near data should gen- 
erally go inside the data segment). 
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C.1.2 Entering the Procedure 
Two instructions begin the procedure: 


push bp 
mov bp, sp 


This sequence establishes BP as the “framepointer.” The framepointer is 
used to access parameters and local data, which are located on the stack. 
SP cannot be used for this purpose because it is not an index or base regis- 
ter. Also, the value of SP may change as more data are pushed onto the 
stack. The value of the base register BP, however, will remain constant 
throughout the procedure; consequently, each parameter can be addressed 
as a fixed displacement off of BP. 


The instruction sequence above first saves the value of BP, since it will 
be needed by the calling procedure as soon as the current procedure ter- 
minates. Then BP is loaded with the value of SP in order to capture the 
value of the stack pointer at the time of entry to the procedure. 


C.1.3 Allocating Local Data (Optional) 


An assembly procedure can use the same technique for allocating local 
data as that used by higher-level languages. To set up local data space, 
simply decrease the contents of SP in the third instruction of the pro- 
cedure. (To ensure correct execution, you should always increase or de- 
crease SP by an even amount.) Decreasing the contents of SP reserves 
space on the stack for the local data. The space must be restored at the 
end of the procedure. 


In the following instructions, space is the total size in bytes of the local 
data. Local variables are then accessed as fixed, negative displacements off 


of BP. 


push bp 
mov bp, sp 
sub Sp, space 


mg Example 


push bp 

mov bp, sp 

sub sp,4 

mov WORD PTR [bp-2],0 


mov WORD PTR [bp-4],0 
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The example above uses two local variables, each of which is two bytes in 
size. SP is decreased by four, since there are four bytes total of local data. 
Later, each of the variables is initialized to 0. These variables are never 
formally declared with any assembler directive; the programmer must keep 
track of them manually. 


Local variables are also referred to as dynamic, stack, or automatic vari- 
ables. 


C.1.4 Preserving Register Values 


A procedure called from any of the Microsoft high-level languages should 
preserve the values of SI, DI, SS, and DS (in addition to BP, which is 
already saved). Therefore, push any of these register values that the pro- 
cedure alters. If the procedure does not change the value of any of these 
registers, then the registers do not need to be pushed. Pop any registers 

_ you have previously pushed just before returning (as explained in Section 
C.1.7, “Exiting the Procedure” ). 


The recommended method (used by the high-level languages) is to save 
registers after the framepointer is set and local data (if any) are allocated. 
In the following fragment, DI and SI (in that order) must be popped 
before the end of the procedure. 


Save old framepointer 


push bp ; 

mov bp, sp ; Establish current framepointer 
sub sp,4 3 Allocate local data space 
push si ; Save SI and DI 


push di 


C.1.5 Accessing Parameters 


Once you have established the procedure’s framepointer, allocated local 
data space (if desired), and pushed any registers that need to be preserved, 
you can write the main body of the procedure. In order to write instruc- 
tions that can access parameters, consider the general picture of the stack 
frame after a procedure call, as shown in Figure C.1. 


297 


Microsoft QuickC Compiler Programmer’s Guide _ 


High addresses 


Parameter 
Parameter 


(Stack grows 


each push or 
| 


+ Framepointer (BP) 
points here. 


+ SP points to last item 
placed on stack. 


Low addresses 


Figure C.1 The Stack Frame 


The stack frame for the procedure is established by the following sequence 
of events: 


1. The calling program pushes each of the parameters onto the stack, 
after which SP points to the last parameter pushed. | 


2. The calling program issues a CALL instruction, which causes the 
return address (the place in the calling program to which control 
will ultimately return) to be placed on the stack. This address may 
be either two bytes long (for near calls) or four bytes long (for far 
calls). SP now points to this address. 


3. The first instruction of the called procedure saves the old value of 
BP, with the instruction push bp. SP now points to the saved 
copy of BP. 


4. Use BP to capture the current value of SP with the instruction 
mov bp,sp. BP now points to the old value of BP. 


5. Whereas BP remains constant throughout the procedure, SP may 
be decreased to provide room on the stack for local data or saved 
registers. 


298 


Interfacing C with Assembly Language 


In general, the displacement (off of BP) for a parameter X is equal to 


2 + size of return address 
+ total size of parameters between X and BP 


For example, consider a FAR procedure that has received one parameter, 
a two-byte address. The displacement of the parameter would be 


Argument's displacement + size of return address 
+ 


s 
4 


2 
2 
6 


The argument can therefore be loaded into BP with the following instruc- 
tion: 


mov bx, [bpt+6] 


Once you determine the displacement of each parameter, you may want to 
use string equates or structures so that the parameter can be referenced 
with a single identifier name in your assembly source code. For example, 
the parameter above at BP-+-6 can be conveniently accessed if you put the 
following statement at the beginning of the assembly source file: 


Argl EQU [bp+6] 


You could then refer to this parameter as Argl in any instruction. Use of 
this feature is optional. 


Note 


Microsoft high-level languages always push segment addresses before 
pushing offset addresses. Furthermore, when arguments larger than 
two bytes are pushed, high-order words are always pushed before low- 
order words. 


C.1.6 Returning a Value (Optional) 


The Microsoft high-level languages share similar conventions for receiving 
return values. The conventions are the same when the data type to be re- 
turned is simple (that is, not an array or structured type) and is no more 
than four bytes long. This includes all near and far address types (in other 
words, all pointers and all parameters passed by reference). 
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Data size Returned in register 

1 byte AL 

2 bytes AX 

4 bytes High-order portion (or segment address) in DX; 


low-order portion (or offset address) in AX 


When the return value is larger than four bytes, a procedure called by C 
must allocate space for the return value and then place its address in 
DX:AX. A convenient way to create space for the return value is to sim- 
ply declare it in a data segment. 


C.1.7 Exiting the Procedure 


Several steps may be involved in terminating the procedure: 


1. If any of the registers SS, DS, SI, or DI have been saved, these 
must be popped off the stack in the reverse order that they were 
saved. 


2. If local-data space was allocated at the beginning of the. procedure, 
SP must be restored with the instruction mov sp,bp. 


3. Restore BP with pop bp. This step is always necessary. 


4. Finally, return to the calling program with ret. The C calling 
module will automatically adjust the stack with respect to the 
parameters that were pushed by the caller. 


m Examples 


pop bp 
ret 


The example above shows the simplest possible exit sequence. No registers 
were saved, no local data space was allocated, and the C calling conven- 
tion is in use. 


pop aa ; Pop saved regs 

pop si 

mov sp,bp 3; Remove local-data space 

pop bp ; Restore old framepointer 

ret 6 ; Exit and restore 6 bytes of args 
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The example above shows an exit sequence for a procedure that has previ- 
ously saved SI and DI, allocated local-data space, and uses a non-C calling 
convention. The procedure must therefore use ret 6 to restore the six 
bytes of parameters on the stack. 


C.2 Calling Assembly-Language Routines 


from C 


A C program can call an assembly procedure in another module, just as it 
would call a C function. In addition to the steps outlined in Section C.1, 
“Writing the Assembly Procedure,” the following guidelines may be 
helpful: 


I 


Declare procedures called from C as far if the C module is compiled 
in large, huge, or medium model, and near if the C module is com- 
piled in small or compact model. 


‘The near and far keywords can override these defaults. The cor- 
rect declaration for the procedure is made implicitly when you use 
the MODEL directive that is available in the Microsoft Macro 
Assembler, Version 5.0. 


Observe the C calling convention. 


The C calling convention pushes parameters onto the stack in the 
reverse order in which they appear in the source code. For example, 
the C function call calc (a,b); pushes b onto the stack before 
it pushes a. In contrast with the other high-level languages, the C 
calling convention specifies that a calling routine always restores 
the stack immediately after the called routine returns control. 


The C convention makes calling with a variable number of parame- 
ters possible. ae the first parameter is always the last one 
pushed, it is always on the top of the stack; therefore it has the 
same address relative to the framepointer, regardless of how many 
parameters were actually passed.) To call with a variable number 
of parameters, use the following steps: 


a. Return with a simple ret instruction. Do not restore the stack 
with ret svze, since the calling C routine will restore the stack 
itself, as soon as it resumes control. 


b. Parameters are placed on the stack in the reverse order that 
they appear in the C source code. The first parameter will be 
lowest in memory (because it is the last parameter to be placed 
on the stack, and the stack grows downward). 
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c. By default, C parameters are passed by value, except for 
arrays, which are passed by reference. 


3. Observe the C naming convention. 


Include an underscore in front of any name which will be shared 
publicly with C. Only the first eight characters of any name are 
recognized by C, so do not make names shared with C longer than 
eight characters. Also, if you plan to link with the 
/NOIGNORECASE option, remember that C is case sensitive 


and does not convert names to uppercase. 


In the following example program, C calls an assembly procedure that 
calculates A + 2*8, where A and B are the first and second parameters, 
respectively. The calculation is performed by shifting the bits in A to the 
left B times. 


The C program uses an extern declaration to create an interface with the 


assembly procedure. No special keywords are required because the assem- 
bly procedure will use the C calling convention. 


extern int power2 (int, int); 
main () 


printf("3 times 2 to the power of 5 is %d\n", power2(3,5)):; 


To understand how to write the assembly procedure, consider how the 
parameters are placed on the stack, as illustrated in Figure C.2. 


High addresses 


(Stack grows 
downward with 


each push or 
Call.) 


Low addresses 


Figure C.2 The C Stack Frame 
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The return address is two bytes long, assuming that the C module is com- 
piled in small or compact model. If the C module is compiled in large, 
huge, or medium model, then the addresses of Arg 1 and Arg 2 are 
each increased by two, to BP+6 and BP+8, respectively, because the 
return address will be four bytes long. 


The first parameter, Arg 1, is lower in memory than Arg 2 because C 
pushes arguments in the reverse order that they appear. Each argument is 
passed by value. 


The assembly procedure can be written as follows: 


-MODEL SMALL 
. CODE 

PUBLIC W_power2 
_power2 PROC 


push bp ; Entry sequence - save old BP 
mov bp, sp 3; Set stack framepointer 
mov ax, [bpt4] ; Load Argl into AX 


mov cx, [bpt6] : Load Arg2 into CX 
shl ax,cl ; AX = AX « (2 to power of CX) 
; Leave return value in AX 


pop bp : aie sequence - restore old BP 
ret , Return 

_power2 ENDP 
END 


The example above assumes that the C module is compiled in small model. 
The parameter offsets and the .MODEL directive will change for different 
models. 


Note that ret without a size variable is used, since the caller will adjust 
the stack upon return from the call. 


C.3 Calling C from Assembly Language 


High-level-language routines assume that certain initialization code has 
previously been executed; you can ensure that the proper initialization is 
performed by starting in a high-level language module, and then calling an 
assembly procedure. The assembly procedure can then call high-level- — 
language routines as needed, as shown in Figure C.3. 
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Assembly code 


(C start-up) 


main(){ 
asub(); 
} 


(C termination) 


call ctest 


ret 
ENDP asub 


Figure C.3 Assembly Call to C 


To execute an assembly call to a high-level language, you need to observe 
the following guidelines: 
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Push each parameter onto the stack, observing the calling conven- 
tion of the high-level language. Constants such as offset addresses 
must first be loaded into a register before being pushed. 


With long parameters, always push the segment or high-order por- 
tion of the parameter first, regardless of the calling convention. 


Execute a call. The call must be far unless the high-level-language 
routine is small model. 


If the routine used the C calling convention, then immediately 
after the call clear the stack of parameters with the instruction 


add sp, size 


where szze is the total size in bytes of all parameters that were 
pushed. 


Interfacing C with Assembly Language 


C.4. The Microsoft Segment Model 


If you use the simplified segment directives by themselves, you do not need 
to know the names assigned for each segment. However, versions of the 
Macro Assembler prior to 5.0 do not support these directives. With older 
versions of the assembler, you should use the SEGMENT, GROUP, 
ASSUME, and ENDS directives equivalent to the simplified segment 
directives. 


Table C.1 shows the default segment names created by each directive. Use 
of these segments ensures compatibility with Microsoft languages and will 
help you to access public symbols. 


The table is followed by a list of three steps illustrating how to make the 
actual declarations, and an example program. 


Table C.1 
Default Segments and Types for Standard Memory Models 
Model __— Directive Name Align Combine Class Group 
Small -CODE _TEXT WORD PUBLIC ’CODE’ 
DATA DATA WORD PUBLIC ’DATA’ DGROUP 
-CONST CONST WORD PUBLIC ’CONST’ DGROUP 
DATA? _BSS WORD PUBLIC ’BSS’ DGROUP 
STACK STACK PARA STACK ’STACK’? DGROUP 
Medium .CODE name_TEXT WORD PUBLIC ’CODE’ 
-DATA DATA WORD PUBLIC ’DATA’ DGROUP 
-CONST CONST WORD PUBLIC ’CONST’ DGROUP 
DATA? _BSS WORD PUBLIC ’BSS’ DGROUP 
STACK STACK PARA STACK ’STACK’ DGROUP 
Compact .CODE _TEXT WORD PUBLIC ’CODE’ 
FARDATA FAR_DATA PARA Private "FAR_DATA’ 
-FARDATA? FAR_BSS PARA Private *"FAR_BSS’ 
DATA _DATA WORD PUBLIC ’DATA’ DGROUP 
-CONST CONST WORD PUBLIC ’CONST’ DGROUP 
-DATA? _BSS WORD PUBLIC ’BSS’ DGROUP 
STACK STACK PARA STACK ’STACK’ DGROUP 
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Table C.1 (continued) 


Model Directive Name Align Combine Class Group 
Large .CODE name_TEXT WORD PUBLIC ’CODE’ 
‘FFARDATA FAR_DATA PARA Private *"FAR_DATA’ 
FFARDATA? FAR_BSS PARA Private *"FAR_BSS’ 
DATA DATA WORD PUBLIC ’DATA’ DGROUP 
CONST CONST WORD PUBLIC ’CONST?’ DGROUP 
‘DATA? _BSS WORD PUBLIC ’BSS’ DGROUP 
STACK STACK PARA STACK ’STACK’ DGROUP 


The directives in Table C.1 refer to the following kinds of segments: 


Directive 


-CODE | 


DATA 
-DATA? 


-FARDATA and 
-FARDATA? 


-CONST 


STACK 


Description of Segment 


Segment containing all the code for the 
module. 


Initialized data. 


Uninitialized data. Microsoft compilers store 
uninitialized data separately because such 
data can be stored more efficiently than ini- 
tialized data. 


Data that will not be combined with the 
corresponding segments in other modules. 
The segment of data placed here can always 
be determined, however, with the assembler 
SEG operator. 


Constant data. Microsoft compilers use this 
segment for items such as string and floating- 
point constants. 


Stack. Normally, this segment is declared in 
the main module for you and should not be 
redeclared. 


Use the following steps with Table C.1 to create actual directives: 


1. Use the indicated name, align type, combine type, and class in a 
segment definition. Thus, the code segment for small model would 
be declared as follows: 
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WORD PUBLIC 'CODE' 


If the combine type is private, simply do not use any combine type. 


If you have segments in DGROUP, put them into D@ROUP 
with the GROUP directive, as in 


GROUP DGROUP 


_DATA _BSS 


Use ASSUME and ENDS as you would normally. Bear in mind 
that, upon entry, DS and SS will both point to D@ROUP. 


The following example shows the C-assembly program from Section C.3, 
but without the simplified segment directives from Version 5.0 of the 
Microsoft Macro Assembler: 


_TEXT 


SEGMENT WORD PUBLIC 


ASSUME 
PUBLIC 


_Power2 PROC 


push 
mov 


mov 
mov 
shl 


pop 
ret 


_Power2 ENDP 


TEXTE 


ENDS 
END 


cs:_TEXT 
_Power2 


bp 
bp, sp 


ax, [bp+4] 


cx, [bpt+6] 
ax,cl 


bp 


Ne Ne Se Ne 


“CODE * 


Entry sequence - save BP 
Set stack frame 


Load Argl into AX 

Load Arg2 into CX 

AX = AX * (2 to power of CX) 
Leave return value in AX 


Exit sequence - restore BP 
Return 
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This appendix lists error messages you may encounter as you develop a 
program and gives a brief description of actions you can take to correct 
the errors. The following list tells where to find error messages for the 
various components of the Microsoft QuickC Compiler: 


Component Section 

The Microsoft QuickC Section D.1, “Compiler Error Mes- 
Compiler sages” 

The command line used to Section D.2, “Command-Line Error 
invoke the Microsoft Messages” 

QuickC Compiler ' 

The Microsoft C run-time Section D.3, “Run-Time Error Mes- 
libraries and other run-time sages” 

situations 

The Microsoft Overlay Section D.4, “LINIC Error Messages” 
Linker, LINK 

The Microsoft Library Section D.5, “LIB Error Messages” 
Manager, LIB 

The Microsoft Program- Section D.6, “MAKI Error Messages” 


Maintenance Utility, 

MAKE 
Note that compiler, command-line, and run-time error messages are listed 
alphabetically in this appendix. 


See Section D.1.4 for information about compiler limits and Section D.3.3 
for information about run-time limits. 


D.1 Compiler Error Messages 


The error messages produced by the C compiler fall into three categories: 


1. Fatal-error messages 

2. Compilation error messages 

3. Warning messages 
The messages for each category are listed below in numerical order, with a 
brief explanation of each error. To look up an error message, first deter- 


mine the message category, then find the error number. Each message that 
is generated within the QuickC environment appears in the error window; 
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the cursor is moved to the line that caused the error (see Section 7.3.4 for 
more information). Each message that is generated by compiling with the 
QCL command gives the file name and line number where the error 
occurs. 

Fatal-Error Messages 

Fatal-error messages indicate a severe problem, one that prevents the com- 
piler from processing your program any further. These messages have the 
following format: 

filename(line) : fatal error Clzzrr: messagetext 

After the compiler displays a fatal-error message, it terminates without 
producing an object file or checking for further errors. 


Compilation-Error Messages 


Compilation-error messages identify actual program errors. These mes- 
sages appear in the following format: 


filename(line) : error C2zrrzx: messagetezt 

The compiler does not produce an object file for a source file that has com- 
pilation errors in the program. When the compiler encounters such errors, 
it attempts to recover from the error. If possible, it continues to process 
the source file and produce error messages. If errors are too numerous or 
too severe, the compiler stops processing. 


Warning Messages 


Warning messages are informational only; they do not prevent compilation 
and linking. These messages appear in the following format: 


filename(line) : warning C4zzrz :messagetezt 


You can use page Abe option to control the level of warnings that the com- 
piler generates. This option is described in Section 9.3.1. 


D.1.1 Fatal-Error Messages 


The following messages identify fatal errors. The compiler cannot recover 
from a fatal error; it terminates after printing the error message. 
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Number 


C1000 


C1001 


C1002 


CLO03 


C1004 


C1005 


Error-Message Reference 


Fatal-Error Message 


UNKNOWN FATAL ERROR 
Contact Microsoft Technical Support 


An unknown error condition was detected by the compiler. 


Please report this condition to Microsoft Corporation, 
using the Product Assistance Request form at the back of 
this manual. 


Internal Compiler Error 
Contact Microsoft Technical Support 


The compiler detected an internal inconsistency. 


Please report this condition using the Product Assistance 
Request form at the back of this manual. Please include the 
file name and line number where the error occurred in this 
report; note that the file name refers to an internal com- 
piler file, not your source file. 


out of heap space 


The compiler ran out of dynamic memory space. This usu- 
ally means that your program has too many symbols 
and/or complex expressions. 


To correct the problem, divide the file into several smaller 
source files, or break expressions into smaller subexpres- 
sions. 


error count exceeds n; stopping compilation 
Errors in the program were too numerous or too severe to 
allow recovery, and the compiler must terminate. 
unexpected EOF 


This message appears when you have insufficient space on 
the default disk drive for the compiler to create the tem- 
porary files it needs. The space required is approximately 
two times the size of the source file. This message can also 
occur when a comment does not have a closing delimiter 
(*/), or when an #if directive occurs without a correspond- 
ing closing # endif directive. 


string too big for buffer 


A string in a compiler intermediate file overflowed a buffer. 


313 


Microsoft QuickC Compiler Programmer’s Guide 


Number 


C1006 


C1007 


C1009 


C1010 


C1012 


C1013 


C1014 
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Fatal-Error Message 


write error on compiler intermediate file 


The compiler was unable to create the intermediate files 
used in the compilation process. 


The following conditions commonly cause this error: 


1. Too few files in the 


files=numober 


line of the CONFIG.SYS file (the compiler 


requires number to be at least 15) 
2. Not enough space on a device containing a compiler 

intermediate file 
unrecognized flag ‘string’ in ‘'option' 
The string in the command-line optzon was not a valid 
option. 
compiler limit 
possibly a recursively defined macro 
The expansion of a macro exceeds the available space. 
Check to see if the macro is recursively defined, or if the 
expanded text is too large. 
compiler limit : macro expansion too big 


The expansion of a macro exceeds the available space. 


bad parenthesis nesting - missing 'character' 
The parentheses in a preprocessor directive were not 
matched; character is either a left or right parenthesis. 
cannot open source file 'filename' 


The given file either did not exist, could not be opened, or 
was not found. Make sure your environment settings are 


valid and that you have given the correct path name for 
the file. 


too many include files 


Nesting of # include directives exceeds the 10-level limit. 


Number 


CTOlS 


C1016 


C1017 


C1018 


C1019 


C1020 


C1021 


C1022 


C1026 


Error-Message Reference 


Fatal-Error Message 


cannot open include file 'filename' 

The given file either did not exist, could not be opened, or 
was not found. Make sure your environment settings are 
valid and that you have given the correct path name for 
the file. 

#if[n]def expected an identifier 

You must specify an identifier with the #ifdef and 

# ifndef directives. 

invalid integer constant expression 

The expression in an #if directive must evaluate to a 
constant. 

unexpected ‘#elif' 

The #elif directive is legal only when it appears within an 
# if, #ifdef, or #ifndef directive. 

unexpected '#else' 

The #else directive is legal only when it appears within an 
#if, #ifdef, or # ifndef directive. 

unexpected '#endif' 

An #endif directive appears without a matching #if, 

# ifdef, or #ifndef directive. 

bad preprocessor command ' string’ 

The characters following the number sign (7) do not form 
a valid preprocessor directive. 

expected '#endif' 

An # if, # ifdef, or #ifndef directive was not terminated 
with an #endif directive. 

parser stack overflow, please simplify your 
program 


Your program cannot be processed because the space 
required to parse the program causes a stack overflow in 
the compiler. 


To solve this problem, try to simplify your program. 
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Number 


C1027 


C1028 


C1032 


C1033 


C1034 


C1035 


C1036 
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Fatal-Error Message 


compiler limit : struct/union nesting 
Structure and union definitions were nested to more than 
10 levels. 

segment segment allocation exceeds 64K 


More than 64IK< of far data were allocated to the given seg- 
ment. A single module can have only 64K of far data. 


To solve this problem, either break declarations up into 
separate modules, reduce the amount of data your program 
uses, or compile your program with the Microsoft C Optim- 
izing Compiler. 
cannot open object listing file ‘filename' 
One of the following statements about the file name or path 
name given (filename) is true: 

1. The given name is not valid. 


2. The file with the given name cannot be opened for 
lack of space. 


3. Aread-only file with the given name already exists. 
cannot open assembly-language output file 
" filename' 
One of the conditions listed under error message C1032 
prevents the given file from being opened. 
cannot open source file ‘'/filename' 
One of the conditions listed under error message C1032 
prevents the given file from being opened. 
expression too complex, please simplify 


The compiler was unable to generate code for a complex 
expression. 


To solve this problem, break the expression into simpler 
subexpressions and recompile. 
cannot open source listing file 'filename' 


One of the conditions listed under error message C1032 
prevents the given file from being opened. 


Number 


C1037 


C1039 


C1040 


C1041 


C1042 


C1043 


Error-Message Reference 


Fatal-Error Message 


cannot open object file ‘filename’ 


One of the conditions listed under error message C1032 
prevents the given file from being opened. 


unrecoverable heap overflow in Pass 3 


The post-optimizer compiler pass overflowed the heap and 
could not continue. 


Try recompiling with the Optimizations option turned on 
(within the QuickC programming environment) or with the 
{Od eeer i the QCL command line), or try breaking 
up the function containing the line that caused the error. 


unexpected EOF in source file 'filename' 


The compiler detected an unexpected end-of-file condition 
while creating a source listing or source/object listing. 


This error probably occurred because the source file was 
edited during compilation. 


cannot open compiler intermediate file — 
no more files 


The compiler could not create intermediate files used in the 
compilation process because no more file handles were 
available. 


This error can usually be corrected by changing the 
files=number line in CONFIG.SYS to allow a larger 
number of open files (20 is the recommended setting). 


cannot open compiler intermediate file — 
no such file or directory 


The compiler could not create intermediate files used in the 
compilation process because the TMP environment vari- 
able was set to an invalid directory or path. 

cannot open compiler intermediate file 


The compiler could not create intermediate files used in the 
compilation process. The exact reason is unknown. 
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Number 


C1044 


C1045 


C1047 


C1048 


C1043 


C1050 


C1052 
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Fatal-Error Message 
out of disk space for compiler intermediate 
file 


The compiler could not create intermediate files used in the 
compilation process because no more space was available. 


To correct the problem, make more space available on the 
disk and recompile. 
floating point overflow 


The compiler generated a floating-point exception while 
doing constant arithmetic on floating-point items at com- 
pile time, as in the following example: 


float fp_val = 1.0e100; 


In this example, the double-precision constant 1.0e100 
exceeds the maximum allowable value for a floating-point 
data item. 

too many option flags, 'string' 

The option appeared too many times. The string contains 
the occurrence of the option that caused the error. 
Unknown option '‘character' in '‘optionstring' 


The character was not a valid letter for optionstring. 


invalid numerical argument 'string' 


A numerical argument was expected instead of string. 


code segment 'segmentname’ too large 
A code segment grew to within 36 bytes of 64K during com- 
pilation. 


A 36-byte pad is used because of a bug in some 80286 chips 
that can cause programs to exhibit strange behavior when, 
among other conditions, the size of a code segment is 
within 36 bytes of 64K. 


too many #if/#ifdef's 


The program exceeded the maximum nesting level for 
# if /# ifdef directives. 


Number 


C1033 


C1054 


CLOSG 


CLOS? 


CLOS9 


C1060 


EFrror-Message Reference 


Fatal-Error Message 


DGROUP data allocation exceeds 64K 


More than 64K of variables were allocated to the default 
data segment. 


For compact-, medium-, or large-model programs, compile 
with the QCL command and use the /Gt option to move 
items into separate segments. 


compiler limit : initializers too deeply 
nested 


The compiler limit on nesting of initializers was exceeded. 
The limit ranges from 10 to 15 levels, depending on the 
combination of types being initialized. 


To correct this problem, simplify the data type being ini- 
tialized to reduce the levels of nesting, or assign initial 
values in separate statements after the declaration. 


compiler limit : out of macro expansion 
space 

The compiler overflowed an internal buffer during the 
expansion of a macro. 


unexpected EOF in macro expansion; (missing 
b] t 

)"?) 
The compiler encountered the end of the source file while 
gathering the arguments of a macro invocation. Usually 
this is the result of a missing closing right parenthesis ( ) ) 
on the macro invocation, as in the following example: 


#define print (a) printf(string is (,#a)) 
main () 


print (the quick brown fox; 


out of near heap space 

The compiler ran out of storage for items that it stores in 
the “near” (default data segment) heap. 

out of far heap space 


The compiler ran out of storage for items that it stores in 
the far heap. 
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Number 


C1LOGT 


C1063 


Fatal-Error Message 


Usually this error occurs in in-memory programs because 
the symbol table contains too many symbols. To fix this 
error, try compiling with the Debug option turned off, or 
try including fewer include files. If these solutions do not 
work, try compiling the program using the QCL command. 


compiler limit : blocks too deeply nested 


Nested blocks in the program exceeded the nesting limit 
allowed by the compiler. 


To correct this problem, rewrite the program so that fewer 
blocks are nested within other blocks. 
compiler limit--compiler stack overflow 


Your program was too complex and caused the compiler 
stack to overflow. Simplify your program and recompile. 


D.1.2 Compilation-Error Messages 


The messages listed below indicate that your program has errors. When 
the compiler encounters any of the errors listed in this section, it continues 
parsing the program (if possible) and outputs additional error messages. 
However, no object file is produced. 


Number 


C2000 


C2001 


C2002 


C2003 
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Compilation-Error Message 

UNKNOWN ERROR 

Contact Microsoft Technical Support 

The compiler detected an unknown error condition. 
Please report this condition to the Microsoft Corporation, 
using the Product Assistance Request form at the back of 
this manual. 

newline in constant 

A new-line character in a character or string constant was 
not in the correct escape-sequence format (\n). 

out of macro actual parameter space 


Arguments to preprocessor macros exceeded 256 bytes. 


expected ‘defined id' 


The identifier to be checked in an #if directive was not 
found. 


Number 


C2004 


C2005 


C2006 


C2007 


C2008 


C2009 


C2010 


C2011 


C2012 


C2013 


C2014 


Error-Message Reference 


Compilation-Error Message 


expected 'defined(id)' 


An #if directive caused a syntax error. 


#line expected a line number 

A #line directive lacked the required line-number speci- 
fication. 

#include expected a file name 

An # include directive lacked the required file-name speci- 
fication. 

#define syntax 


A # define directive caused a syntax error. 


‘character' : unexpected in macro definition 
The given character was used incorrectly in a macro 
definition. 

reuse of macro formal ‘'vdentifier' 

The given identifier was used twice in the formal-parameter 
list of a macro definition. 

‘character’ : unexpected in formal list 

The given character was used incorrectly in the formal- 
parameter list of a macro definition. 

‘identifier’ : definition too big 


The given macro definitions exceeded 256 bytes. 


missing name following ‘'<' 

An # include directive lacked the required file-name 
specification. 

missing '>' 

The closing angle bracket (>) was missing from an 

# include directive. 

preprocessor command must start as first 
non-whitespace 


Non-white-space characters appeared before the number 
sign (#£) of a preprocessor directive on the same line. 
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Number 


C2015 


C2O0E6 


C2017 


C2018 


C2019 


C2020 


C2021 


C2022 


C2023 


C2024 
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Compilation-Error Message 


too many chars in constant 

A character constant containing more than one character 
or escape sequence was used. 

no closing single quote 

A character constant was not enclosed in single quotation 
marks. 

illegal escape sequence 

The character or characters after the escape character (\) 
did not form a valid escape sequence. 

unknown character 'Oxcharacter' 

The given hexadecimal number did not correspond to a 
character. 

expected preprocessor command, found 

' character’ 

The given character followed a number sign (#), but it was 
not the first letter of a preprocessor directive. 

bad octal number ‘character’ 


The given character was not a valid octal digit. 


expected exponent value, not 'character' 

The given character was used as the exponent of a float- 
ing-point constant but was not a valid number. 
‘number’ : too big for char 


The number was too large to be represented as a character. 


divide by O 


The second operand in a division operation (/) evaluated to 
O, giving undefined results. 


mod by O 


The second operand in a remainder operation (%) 
evaluated to 0, giving undefined results. 


Number 


CZO0Z95 


C2026 


C2028 


C2029 


C2030 


C2031 


Error-Message Reference 


Compilation-Error Message 


‘adentifier' : enum/struct/union type 
redefinition 


The given identifier had already been used for an enumera- 
tion, structure, or union tag. 


‘adentifier' : member of enum redefinition 


The given identifier had already been used for an enumera- 
tion constant, either within the same enumeration type or 
within another enumeration type with the same visibility. 


struct/union member ne€éds to be inside a 
struct/union 


Structure and union members must be declared within the 
structure or union. 


This error may be caused by an enumeration declaration 
that contains a declaration of a structure member, as in the 
following example: 


enum a { 
january, 
february, 
int march; /* structure declaration: 
** illegal 
a / 
}: 
‘edentifier' : bit-fields allowed only in 
structs 


Only structure types may contain bit fields. 


‘adentifier' ; struct/union member redefinition 
The identifier was used for more than one member of the 
same structure or union. 

‘edentifier' : function cannot be struct/union 
member 


The given function was declared to be a member of a struc- 
ture or union. 


To correct this error, use a pointer to the function instead. 
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Number 


CZ022 


G2Z033 


C2034 


C2039 


C2036 


C2037 


C2038 


C2039 
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Compilation-Error Message 

‘identifier’ : base type with near/far/huge not 
allowed 

The given structure or union member was declared with the 
near or far keyword. 

‘identifier’ : bit-field cannot have 
indirection 

The given bit field was declared as a pointer (*), which is 
not allowed. 

‘identifier’ : bit-field type too small for 
number of bits 

The number of bits specified in the bit-field declaration 
exceeded the number of bits in the given base type. 
enum/struct/union ‘identifier’ : unknown size 


The given structure or union had an undefined size. 


left of '‘member' must have struct/union type 


The expression before the member-selection operator (~>) 
was not a pointer to a structure or union type, or the 
expression before the member-selection operator (.) did not 
evaluate to a structure or union. In this message, member is 
a member designator in one of the following forms: 


— >identrfrer 


. identifier 
left of '—>' or '.' specifies undefined 
struct/union 


The expression before the member-selection operator (-> 
or .) identified a structure or union type that was not de- 
fined. 


‘edentifier' : not struct/union member 

The given identifier was used in a context that required a 
structure or union member. 

'"—>' requires struct/union pointer 


The expression before the member-selection operator (—> 
was a structure or unlon name, not a pointer to a structure 
or union as expected. 


Number 


C2040 


C2041 


C2042 


C2043 


C2044 


C2045 


C2046 


C2047 


C2048 


Error-Message Reference 


Compilation-Error Message 
'.' requires struct/union name 


The expression before the member-selection operator (.) 
was a pointer to a structure or union, not a structure or 
union name as expected. 

keyword 'enum' illegal 

The enum keyword appeared in a structure or union 
declaration, or an enum type definition was not formed 
correctly. 

signed/unsigned keywords mutually exclusive 
Both the signed and the unsigned keywords were used in 
a single declaration, as in the following example: 
unsigned signed int i; 


illegal break 

A break statement is legal only when it appears within a 
do, for, while, or switch statement. 

illegal continue 

A continue statement is legal only when it appears within 
a do, for, or while statement. 

‘adentifier' : label redefined 

The given label appeared before more than one statement 
in the same function. 

illegal case 

The case keyword may appear only within a switch 
statement. 

illegal default 

The default keyword may appear only within a switch 
statement. 

more than one default 


A switch statement contained more than one default 
label. 


Microsoft QuickC Compiler Programmer’s Guide 


Number 


C2050 


C2051 


CZO0S2 


C2053 


C2054 


C2055 


C2056 


C20a7 


C2038 


C2039 


C2060 
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Compilation-Error Message 


non-integral switch expression 


A switch expression was not integral. 


case expression not constant 


Case expressions must be integral constants. 


case expression not integral 


Case expressions must be integral constants. 


case value number already used 

The given case value was already used in this switch state- 
ment. 

expected '(' to follow 'vdentzfier' 

The context requires parentheses after the function 
identifier. 

expected formal parameter list, not a type 
list 

An argument-type list appeared in a function definition 
instead of a formal parameter list. 

illegal expression 

An expression was illegal because of a previous error. (The 
previous error may not have produced an error message.) 
expected constant expression 


The context requires a constant expression. 


constant expression is not integral 


The context requires an integral constant expression. 


syntax error : 'token' 


The given token caused a syntax error. 


syntax error : EOF 


The end of the file was encountered unexpectedly, causing a 
syntax error. This error can be caused by a missing closing 
brace (}) at the end of your program. 


Number 


C2061 


C2062 


C2063 


C2064 


C2065 


C2066 


C2067 


C2068 


C2069 


C2070 


C2071 


C2072 


Error-Message Reference 


Compilation-Error Message 


syntax error : identifier ‘zdenizfier' 


The given identifier caused a syntax error. 
type ‘type' unexpected 
The given type was misused. 


‘identifier’ : not a function 


The given identifier was not declared as a function, but an 
attempt was made to use it as a function. 


term does not evaluate to a function 


An attempt was made to call a function through an expres- 
sion that did not evaluate to a function pointer. 


‘identifier' : undefined 
The given identifier was not defined. 


cast to function returning. .. is illegal 


An object was cast to a function type. 


cast to array type is illegal 
An object was cast to an array type. 


illegal cast 


A type used in a cast operation was not a legal type. 


cast of 'void' term to non-void 


The void type was cast to a different type. 


illegal sizeof operand © 


The operand of a sizeof expression was not an identifier or 
a type name. 


'class' : bad storage class 


The given storage class cannot be used in this context. 


‘identifier’ : initialization of a function 


An attempt was made to initialize a function. 
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Number 


C2073 


C2074 


C2075 


C2076 


C2077 


C2078 


C2079 


C2082 


Compilation-Error Message 
‘adentifier' : cannot initialize array in 
function 


An attempt was made to initialize the given array within a 
function. 


Arrays can be initialized only at the external level. 


cannot initialize struct/union in function 


An attempt was made to initialize the given structure or 
union within a function. Structures and unions can be ini- 
tialized only at the external level. 


‘identifier’ : array initialization needs curly 
braces 

The braces ({ }) around the given array initializer were 
missing. 

‘identifier’ : struct/union initialization 
needs curly braces 

The braces ({ }) around the given structure or union initial- 
izer were missing. 

non-integral field initializer ‘zdentzfier' 

An attempt was made to initialize a bit-field member of a 
structure with a nonintegral value. 

too many initializers 

The number of initializers exceeded the number of objects 
to be initialized. 

‘edentifier’ is an undefined struct/union 

The given identifier was declared as a structure or union 
type that had not been defined. 

redefinition of formal parameter 'identifier' 


A formal parameter to a function was redeclared within the 
function body. 


Number 


C2083 


C2084 


C2085 


C2086 


C2087 


C2088 


Error-Message Reference 


Compilation-Error Message 


array ‘identifier’ already has a size 

The dimensions of the given array had already been 
declared. 

function ‘identifier’ already has a body 


The given function had already been defined. 


‘identifier’ : not in formal parameter list 
The given parameter was declared in a function definition 
for a nonexistent formal parameter. 

‘adentifier' : redefinition 


The given identifier was defined more than once. 


‘edentifier' : missing subscript 


The definition of an array with multiple subscripts was 
missing a subscript value for a dimension other than the 
first dimension, as in the following example: 


int func (a) 


Fas a[10] []: /* Illegal «/ 
} 
int func (a) 
char a[] [5]; /* Legal */ 
aS 
} 


use of undefined enum/struct/union '‘identzfier' 


The given identifier referred to a structure or union type 
that was not defined. 
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Number 


C2089 


C2090 


C2091 


C2092 


C2093 


C2094 


330 


Compilation-Error Message 


typedef specifies a near/far function 


The use of the near or far keyword in a typedef declara- 
tion conflicted with the use of near or far for the declared 
item, as in the following example: 


typedef int far FARFUNC( ): 
FAREUNC near «fp; 


function returns array 

A function cannot return an array. (It can return a pointer 
to an array.) 

function returns function 

A function cannot return a function. (It can return a 
pointer to a function.) 

array element type cannot be function 
Arrays of functions are not allowed; however, arrays of 
pointers to functions are allowed. 

cannot initialize a static or struct with 
address of automatic vars 


The program tried to use the address of an automatic vari- 
able in the initializer of a static item, as in the following 
example: 


func () 


int 4:3 
static int *ip=&i; 


3 


label ‘vdentifier' was undefined 


The function did not contain a statement labeled with the 
given identifier. 


Error-Message Reference 


Number Compilation-Error Message 
C2095 function : actual has type void : parameter 
number 


Formal parameters and arguments to functions cannot 
have type void; they can, however, have type void * 
(pointer to void). 


C2096 struct/union comparison illegal 


You cannot compare two structures or unions. (You can, 
however, compare individual members of structures and 
unions.) 


C2097 illegal initialization 


An attempt was made to initialize a variable using a non- 
constant value. 


C2098 non-address expression 
An attempt was made to initialize an item that was not an 
Ivalue. 

C2099 non-constant offset 


An initializer used a nonconstant offset. 


C2100 illegal indirection 
The indirection operator (*) was applied to a nonpointer 
value. 

C2101 '&' on constant 
The address-of operator (&) did not have an lvalue as its 
operand. 

C2102 '&' requires lvalue 
The address-of operator must be applied to an Ivalue ex- 
pression. 

C2103 "&' on register variable 


An attempt was made to take the address of a register vari- 


able. 
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Number 


C2104 


C210 


C2106 


C2107 


C2108 


C2109 


C2110 


C2itL 


C2112 


C2113 


C2114 


332 


Compilation-Error Message 


'&' on bit-field 
An attempt was made to take the address of a bit field. 


‘operator' needs lvalue 


The given operator did not have an Ivalue operand. 


‘operator’ : left operand must be lvalue 


The left operand of the given operator was not an lvalue. 


illegal index, indirection not allowed 
A subscript was applied to an expression that did not 
evaluate to a pointer. 

non-integral index 


A nonintegral expression was used in an array subscript. 


subscript on non-array 


A subscript was used on a variable that was not an array. 


'+' : 2 pointers 


An attempt was made to add one pointer to another. 


pointer + non-integral value 

An attempt was made to add a nonintegral value toa 
pointer. 

illegal pointer subtraction 


An attempt was made to subtract pointers that did not 
point to the same type. 


"-' 3; right operand pointer 


The right operand in a subtraction operation (—) was a 
pointer, but the left operand was not. 

‘operator’ : pointer on left; needs integral 
right 


The left operand of the given operator was a pointer; the 
right operand must be an integral value. 


Number 


C2115 


C2116 


Cally 


C2118 


C2i19 


C2120 


C2121 


C2122 


Cai 3 


Error-Message Reference 


Compilation-Error Message 


‘adentifier' : incompatible types 


An expression contained incompatible types. 


operator : bad left (or right) operand 

The specified operand of the given operator was illegal for 
that operator. 

‘operator' : illegal for struct/union 
Structure and union type values are not allowed with the 
given operator. 

negative subscript 


A value defining an array size was negative. 


‘typedefs' both define indirection 


Two typedef types were used to declare an item and both 
ty pedef types had indirection. For example, the declara- 
tion of p in the following example is illegal: 


typedef int *P_INT: 

typedef short *P_SHORT:; 

/* this declaration is illegal s/ 
P_SHORT P_INT p:; 

‘'void' illegal with all types 


The void type was used in a declaration with another type. 


typedef specifies different enum 


An attempt was made to use a type declared in a typedef 
statement to specify both an enumeration type and another 


type. 
typedef specifies different struct 


An attempt was made to use a type declared in a typedef 
statement to specify both a structure type and another 


type. 


typedef specifies different union 


An attempt was made to use a type declared in a typedef 
statement to specify both a union type and another type. 
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Number Compilation-Error Message 


C2125 ‘eidentifier': allocation exceeds 64K 


The given item exceeds the size limit of 64K. 


C2126 identifier: automatic allocation exceeds 32K 
The space allocated for the local variables of a function 
exceeded the given limit. 

C2127 parameter allocation exceeds 32K 
The storage space required for the parameters to a function 
exceeded the limit of 32K. 

C2129 static function ‘identifier' not found 
A forward reference was made to a static function that was 
never defined. 

C2139 #line expected a string containing the file 
name 
A file name was missing from a # line directive. 

C2131 attributes specify more than one 
near /far/huge 
More than one of the keywords near and far were applied 
to an item, as in the following example: 


typedef int near NINT; 
NINT far a; /* Illegal +*/ 


C2132 syntax error : unexpected identifier 


An identifier appeared in a syntactically illegal context. 


C2133 array ‘identifier’ : unknown size 


An attempt was made to declare an unsized array as a local 
variable, as in the following example: 


int mat_add(arrayl1) 


int arrayl[]: /* Legal */ 
int array2[]; /* Illegal +/ 
} 
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Number 


C2134 


C2135 


C2137 


C2138 


C2139 


C2140 


C2141 


C2142 


Error-Message Reference 


Compilation-Error Message 


identifier : struct/union too large 

The size of a structure or union exceeded the compiler limit 
(2° bytes). 

missing ')' in macro expansion 

A macro reference with arguments was missing a closing 
parenthesis. 

empty character constant 

The illegal empty-character constant ('') was used. 


unmatched close comment '/x' 


The compiler detected an open-comment delimiter (/*) 
without a matching close-comment delimiter (*/). 


This error usually indicates an attempt to use illegal nested 
comments. 

type following ‘type’ is illegal 

An illegal type combination, such as the following, was 
used: 


long char a; 


argument type cannot be function returning 


A function was declared as a formal parameter of another 
function, as in the following example: 


int funcl (a) 
Tea, es /* Illegal +«/ 
value out of range for enum constant 
An enumeration constant had a value outside the range of 
values allowed for type int. 
ellipsis requires three periods 


The compiler detected a token consisting of two periods 
(.. ) and assumed that an ellipsis ( ... ) was intended. 
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Number 


C2143 


C2144 


C2145 


C2146 


C2147 


C2148 


C2lAag 


C2150 
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Compilation-Error Message 
syntax error : missing ‘token!' before 
"token2' 


The compiler expected token! to appear before token2. This 
message may appear if a required closing brace (}), right 
parenthesis ()), or semicolon (;) is missing. 


syntax error : missing 'token' before type 

! type! 

The compiler expected the given token to appear before the 
given type name. 


This message may appear if a required closing brace (}), 
right parenthesis ()), or semicolon (;) is missing. 
syntax error : missing '‘'foken' before 
identifier 


The compiler expected the given token to appear before an 
identifier. 


This message may appear if a semicolon (;) does not appear 
after the last declaration of a block. 

syntax error : missing ‘token’ before 
identifier ‘rdentifier' 

The compiler expected the given token to appear before the 
given identifier. 

array : unknown size 

An attempt was made to increment an index or pointer to 
an array whose base type has not yet been declared. 

array too large 


An array exceeded the maximum legal size ios bytes). 


identifier: named bit-field cannot have O width 


The given named bit field had a zero width. Only unnamed 
bit fields are allowed to have zero width. 


wdentifier: bit-field must have type int, 
Signed int, or unsigned int 


The ANSI C standard requires bit fields to have types of 
int, signed int, or unsigned int. This message appears 
only if you compiled your program with the /Za option. 


Error-Message Reference 


Number Compilation-Error Message 


C2ZL5L more than one cdecl/fortran/pascal 
attribute specified 


More than one keyword specifying a function-calling con- 
vention was given. 


C2152 identifier : pointers to functions with 
Gdifferent attributes 


An attempt was made to assign a pointer to a function 
declared with one calling convention (cdecl, fortran, or 
pascal) to a pointer to a function declared with a different 
calling convention. 


C253 hex constants must have at least 1 hex 
digit 
Ox and OX are illegal hexadecimal constants. At least one 


«» 


hexadecimal digit must follow the “x” or “X.” 


C2154 "name' : does not refer to a segment 


The function name was the first identifier given in an 
alloc_ text pragma argument list, and it is already defined 
as something other than a segment name. 


G2iSs 'name' : already in a segment 
The function name appeared in more than one alloc_text 
pragma. 

C2156 pragma must be at outer level 


Certain pragmas must be specified at a global level, outside 
a function body, and one of these pragmas occurred within 
a function. 


C2157 "name' : must be declared before use in 
pragma list 


The function name in the list of functions for an 
alloc_ text pragma was not declared prior to being refer- 
enced in the list. 


C2158 ‘name’ : is a function 


The name was specified in the list of variables in a 
same_ seg pragma, but was previously declared as a func- 
tion. 


337 


Microsoft QuickC Compiler Programmer’s Guide 


Number 


C2159 


C2160 


C2161 


C2162 


C2163 


C2165 


C2166 


338 


Conipilation-Error Message 


more than one storage class specified 

More than one storage class was given in a declaration, as 
in the following example: 

extern static int i; 

## cannot occur at the beginning of a macro 
definition 

A macro definition began with a token-pasting operator 
(#¢ #), as in the following example: 

#define mac(a,b) ##a... 

## Cannot occur at the end of a macro 
definition 

A macro definition ended with a token-pasting operator 
(##). 

expected macro formal parameter 

The token following a stringizing operator (#) was not a 
formal parameter name, as in the following example: 


#define print(a) printf (#b) 


‘string’ : not available as an intrinsic 

A function specified in the list of functions for an intrinsic 
or function pragma is not one of the functions available in 
intrinsic form. 

‘keyword' : cannot modify pointers to data 
The fortran, pascal, or edecl keyword was used illegally 
to modify a pointer to data, as in the following example: 


char pascal +*p; 


lval specifies ‘const' object 


An attempt was made to assign a value to an item declared 
with const storage class. 


Number 


C2167 


C2168 


C2169 


C2i 71 


Cz2iv2 


C2iL73 


Frror-Message Reference 


Compilation-Error Message 


"name' : too many actual parameters for 
intrinsic 

A reference to the intrinsic function name contains too 
many actual parameters. 


'name' : too few actual parameters for 
intrinsic 


A reference to the intrinsic function name contains too few 
actual parameters. 


‘name’ +: is an intrinsic, it cannot be 
defined 


An attempt was made to provide a function definition for a 
function already declared as an intrinsic. 


‘operator’ : bad operand 


The given unary operator was used with an illegal operand 
type, as in the following example: 


int (#fp) (): 
double d,dl: 


fpr; 
2 aes 8 


function : actual is not a pointer, parameter 
number 


An attempt was made to pass a non-pointer argument to a 
function that expected a pointer. The given number indi- 
cates which argument was In error. 


function : actual is not a pointer 
parameter number : parameterlist number 


An attempt was made to pass a non-pointer argument to a 
function that expected a pointer. This error occurs in calls 
that return a pointer to a function. The first number indi- 
cates which argument was in error; the second number indi- 
cates which argument list contained the invalid argument. 
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Number 


C2174 


C2i75 


C2177 


Compilation-Error Message 


function : actual has type void : parameter 
number, parameter list number 


An attempt was made to pass a void argument to a func- 
tion. Formal parameters and arguments to functions can- 
not have type void; they can, however, have type void * 
(pointer to void). This error occurs in calls that return a 
pointer to a function. The first number indicates which 
argument was in error; the second number indicates which 
argument list contained the invalid argument. 


function : unresolved external 


The given function is not defined in the source file, or built 
into the QuickC programming environment, or present in 
the Quick library (if any) that was loaded. 


This error occurs only for single-module, in-memory pro- 
grams. To solve this program, either define the function in 
the source file, load a Quick library containing the function, 
or (if the function is a standard C library function) create a 
program list for the program. 


constant too big 


Information was lost because a constant value was too large 
to be replaced in the type to which it was assigned. (1) 


D.1.3. Warning Messages 


The messages listed in this section indicate potential problems but do not 
hinder compilation and linking. The number in parentheses at the end of 
an error-message description gives the minimum warning level that must 
be set for the message to appear. 


Number 


C4000 
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Warning Message 

UNKNOWN WARNING 

Contact Microsoft Technical Support. 
The compiler detected an unknown error condition. 


Please report this condition to Microsoft Corporation, 
using the Product Assistance Request form at the back of 
this manual. 


Number 


C4001 


C4002 


C4003 


C4004 


C4005 


C4006 


C4009 


C4011 


Error-Message Reference 


Warning Message 


macro ‘identifier' requires parameters 


The given identifier was defined as a macro taking one or 
more arguments, but it was used in the program without 
arguments. (1) 


too many actual parameters for macro 
‘adentifier' 


The number of actual arguments specified with the given 
identifier was greater than the number of formal parame- 
ters given in the macro definition of the identifier. (1) 


not enough actual parameters for macro 
‘adentifier' 


The number of actual arguments specified with the given 
identifier was less than the number of formal parameters 
given in the macro definition of the identifier. (1) 
missing close parenthesis after ‘'defined' 
The closing parenthesis was missing from an # if defined 
phrase. (1) 

‘edentifier' : redefinition 

The given identifier was redefined. (1) 


#undef expected an identifier 

The name of the identifier whose definition was to be 
removed was not given with the # undef directive. (1) 
string too big, trailing chars truncated 

A string exceeded the compiler limit on string size. 

To correct this problem, break the string into two or more 
strings. (1) 

identifier truncated to ‘zdentifier' 


Only the first 31 characters of an identifier are significant. 
1 
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Number 


C4014 


C4015 


C4016 


C4017 


C4020 


C4021 


C4022 


342 


Warning Message 


‘identifier’ : bit-field type must be unsigned 
The given bit field was not declared as an unsigned type. 
Bit fields must be declared as unsigned integral types. The 
compiler converted the given bit field accordingly. (1) 
‘edentifier' : bit-field type must be integral 
The given bit field was not declared as an integral type. 

Bit fields must be declared as unsigned integral types. A 
conversion has been supplied. (1) 

‘adentifier' : no function return type 


The given function had not yet been declared or defined, so 
the return type was unknown. 


The default return type (int) is assumed. (2) 


cast of int expression to far pointer 


A far pointer represents a full segmented address. On an 
8086/8088 processor, casting an int value to a far pointer 
Ay produce an address with a meaningless segment value. 
1 


too many actual parameters 


The number of arguments specified in a function call was 
greater than the number of parameters specified in the 
argument-type list or function definition. (1) 


too few actual parameters 


The number of arguments specified in a function call was 
less than the number of parameters specified in the 
argument-type list or function definition. (1) 


pointer mismatch: parameter n 


The pointer type of the given parameter was different from 
the pointer type specified in the argument-type list or func- 
tion definition. (1) 


Number 


C4024 


C4025 


C4026 


C4027 


C4028 


C4029 


C4030 


Frror-Message Reference 


Warning Message 


different types : parameter n 


The type of the given parameter in a function call did not 
agree with the type given in the argument-type list or func- 
tion definition. (1) 


function declaration specified variable 
argument list 


The argument-type list in a function declaration ended 
with either a comma or a comma followed by ellipsis dots 
(,..-), indicating that the function could take a variable 
number of arguments, but no formal parameters were 
declared for the function. (1) 


function was declared with formal argument 
list 


The function was declared to take arguments, but the func- 
tion definition did not declare formal parameters. (1) 


function was declared without formal 
argument list 


The function was declared to take no arguments (the 
argument-type list consisted of the word void), but formal 
parameters were declared in the function definition, or 
arguments were given in a call to the function. (1) 


parameter n declaration different 


The type of the given parameter did not agree with the 
corresponding type in the argument-type list or with the 
corresponding formal parameter. (1) 


declared parameter list different from 
definition 


The argument-type list given in a function declaration did 
not agree with the types of the formal parameters given in 
the function definition. (1) 


first parameter list is longer than the 
second 


A function was declared more than once with different 
argument-type lists in the declarations. (1) 
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Number 


C4031 


C4032 


C4033 


C4034 


C4035 


C4036 


C4037 


C4038 


344 


Warning Message 

second parameter list is longer than the 
first 

A function was declared more than once with different 
argument-type lists. (1) 

unnamed struct/union as parameter 

The structure or union type being passed as an argument 
was not named, so the declaration of the formal parameter 
cannot use the name and must declare the type. (1) 
function must return a value 

A function is expected to return a value unless it is declared 
as void. (2) 

sizeof returns O 

The sizeof operator was applied to an operand that yielded 
a size of zero. (1) 

wdentzfier : no return value 


A function declared to return a value did not do so. (2) 


unexpected formal parameter list 

A formal-parameter list was given in a function declaration. 
The formal-parameter list is ignored. (1) 

‘adentifier' : formal parameters ignored 


No storage class or type name appeared before the declara- 
tors of formal parameters in a function declaration, as in 
the following example: 


int «f(a,b,c); 
The formal parameters are ignored. (1) 


‘identifier' : formal parameter has bad storage 
class 


The given formal parameter was declared with a storage 
class other than auto or register. (1) 


Number 


C4039 


C4040 


C4041 


C4042 


C4043 


C4045 


C4046 


C4047 


Error-Message Reference 


Warning Message 


‘¢adentifier' : function used as an argument 

A formal parameter to a function was declared to be a func- 
tion, which is illegal. The formal parameter is converted to 

a function pointer. (1) 

near/far/huge on '‘?dentifier' ignored 

The near or far keyword has no effect in the declaration of 
the given identifier and is ignored. (1) 

formal parameter ‘tdentifier' is redefined 


The given formal parameter was redefined in the function 
body, making the corresponding actual argument unavail- 
able in the function. (1) 

‘identifier’ : has bad storage class 


The specified storage class cannot be used in this context 
(for example, function parameters cannot be given extern 
class). The default storage class for that context was used 
in place of the illegal class. (1) 

‘identifier’ : void type changed to int 

An item other than a function was declared to have void 
type. (1) 

‘identifier’ : array bounds overflow 

Too many initializers were present for the given array. The 
excess initializers are ignored. (1) 

'&' on function/array, ignored 

An attempt was made to apply the address-of operator (&) 
to a function or array identifier. (1) 

‘operator': different levels of indirection 


An expression involving the specified operator had incon- 
sistent levels of indirection. (1) 


The following example illustrates this condition: 


char **p?; 
char +*q; 


345 


Microsoft QuickC Compiler Programmer’s Guide 


Number 


C4048 


C4049 


C4051 


C4052 


C4053 


C4056 


C4057 


C4058 


C4059 


C4060 


346 


Warning Message 


array's declared subscripts different 

An array was declared twice with different sizes. The larger 
size is used. (1) 

‘operator' : indirection to different types 
The indirection operator (*) was used in an expression to 
access values of different types. (1) 

data conversion 

Two data items in an expression had different types, caus- 
ing the type of one item to be converted. (2) 

different enum types 


Two different enum types were used in an expression. (1) 


at least one void operand 


An expression with type void was used as an operand. (1) 


overflow in constant arithmetic 
The result of an operation exceeded Ox7FFFFFFF. (1) 


overflow in constant multiplication 
The result of an operation exceeded Ox7FFFFFFF. (1) 


address of frame variable taken, DS != SS 


The program was compiled with the default data segment 
(DS) not equal to the stack segment (SS), and the program 
tried to point to a frame variable with a near pointer. (1) 


segment lost in conversion 


The conversion of a far pointer (a full segmented address) 
to a near pointer (a segment offset) resulted in the loss of 
the segment address. (1) 


conversion of long address to short address 


The conversion of a long address (a 32-bit pointer) to a 
short address (a 16-bit pointer) resulted in the loss of the 
segment address. (1) 


Number 


C4061 


C4062 


C4063 


C4066 


C4067 


C4068 


Error-Message Reference 


Warning Message 


long/short mismatch in argument: conversion 
supplied 
The base types of the actual and formal arguments of a 


function were different. The actual argument is converted 
to the type of the formal parameter. (1) 


near/far mismatch in argument: conversion 
supplied 
The pointer sizes of the actual and formal arguments of a 


function were different. The actual argument is converted 
to the type of the formal parameter. (1) 


‘adentifier' : function too large for post- 
optimizer 


The given function was not optimized because not enough 
space was available. To correct this problem, reduce the 
size of the function by dividing it into two or more smaller 
functions. (0) 


local symbol table overflow - some local 
symbols may be missing in listings 


The listing generator ran out of heap space for local vari- 
ables, so the source listing may not contain symbol-table 
information for all local variables. 


unexpected characters following 'directive' 
directive - newline expected 

Extra characters followed a preprocessor directive, as in the 
following example: 

fendif NO_EXT_KEYS 


This is accepted in some versions of the Microsoft C Com- 
piler, but not in Version 1.0 of the Microsoft QuickC Com- 


piler. (1) 
unknown pragma 


The compiler did not recognize a pragma and ignored it. (1) 


347 


Microsoft QuickC Compiler Programmer’s Guide 


Number 


C4069 


C4071 


C4072 


C4073 


C4074 


C4075 


C4076 


348 


Warning Message 


conversion of near pointer to long integer 


A near pointer was converted to a long integer, which 
involves first extending the high-order word with the 
current data-segment value, not 0. (1) 


‘identifier’ : no function prototype given 


The given function was called before the compiler found the 
corresponding function prototype. (3) 


Insufficient memory to process debugging 
information 


You compiled the program with the /Zi option, but not 
enough memory was available to create the required debug- 
ging information. (1) 


scoping too deep, deepest scoping merged 
when debugging 


Declarations appeared at a static nesting level greater than 
13. As a result, all declarations will seem to appear at the 
same level. (1) 


non standard extension used - '‘'eztension' 


The given nonstandard language extension was used when 
the Language Ixtensions option in the Compile dialog box 
was turned off, or when the /Ze option was in effect. These 
extensions are given in Section 8.1.4.6, “Using Microsoft 
Extensions to C: the Language Extensions Option.” (If the 
is option is in effect, this condition generates an error.) 
3 


size of switch expression or case constant 
too large - converted to int 


A value appearing in a switch or case statement was 
larger than an int type. The compiler converts the illegal 
value to an int type. (1) 

‘type’ : may be used on integral types only 
The signed or unsigned type modifier was used with a 
non-integral type, as in the following example: 


unsigned double x; 


Number 


C4077 


C4079 


C4080 


C4082 


C4083 


C4084 


Error-Message Reference 


Warning Message 


unknown check_stack option 
An unknown option was given with the old form of the 
check_ stack pragma, as in the followling example: 


#pragma check_stack yes 


In the old form of the check_ stack pragma, the argument 
to the pragma must be empty, +, or ~. 
unexpected char 'character' 


An unexpected separator character was found in the argu- 
ment list of a pragma. 


missing segment name 


The first argument in the argument list for the alloc_ text 
pragma was missing a segment name. This happens if the 
first token in the argument list is not an identifier. 


expected an identifier 


There was a missing identifier in the list of arguments to a 
pragma. 


missing ‘'(' 
An opening left parenthesis was missing from the argument 
list for a pragma, as in the following example: 


#pragma check_pointer on) 


expected a pragma keyword 


The token following the keyword pragma was not an 
identifier, as in the following example: 


#pragma (on) 
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Number 


C4085 


C4086 


C4087 


C4090 


C4091 


350 


Warning Message 


expected [onloff] 
An invalid argument was given for the new form of the 
check stack pragma, as in the following example: 


#pragma check_stack (yes) 


expected [1]2|4] 

An invalid argument was given for a pack pragma, as in 
the following example: 

#pragma pack (yes) 


‘name' : declared with void parameter list 


The given function was declared as taking no parameters, 
but a call to the function specified actual parameters, as in 
the following example: 


int: £1 (void) 


£1(10) ; 


different ‘const’ attributes 


A pointer to an item declared as const was passed to a 
function where the corresponding formal parameter was a 
pointer to a non-const item. This means the item could be 
modified by the function undetected, as in the following 
example: 


const char *p = "abcde"; 
int str(char *s): 


str (p); 


no symbols were declared 


The compiler detected an empty declaration, as in the fol- 
lowing example (2): 


int ; 


Number 


C4092 


C4093 


C4095 


C4096 


C4097 


Error-Message Reference 


Warning Message 


untagged enum/struct/union declared no 
symbols 


The compiler detected an empty declaration using an 
untagged structure, union, or enumerated variable, as in 
the following example: 


struct { 


}; 


unescaped newline in character constant in 
non-active code 


The constant expression of an #if, #elif, #ifdef, or 

# ifndef preprocessor directive evaluated to 0, making the 
following code inactive, and a new-line character appeared 
between a single or double quotation mark and the match- 
ing single or double quotation mark in that inactive code. 


too many arguments for pragma 

More than one argument appeared for a pragma that takes 
only one argument. 

huge item treated as far 


Since the Microsoft QuickC Compiler does not support the 
huge keyword, the item is treated as if it had been declared 
with the far keyword. If the item or function must be huge, 
recompile the program with the Microsoft C Optimizing 
Compiler. 


non-ascii character '‘hez-character' in string 


The given non-ASCII character was used in a string. 
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D.1.4 Compiler Limits 


To operate the Microsoft QuickC Compiler, you must have sufficient disk 
space available for the compiler to create temporary files that are used in 
processing. The space required is approximately two times the size of the 
source file. 


Table D.1 summarizes the limits imposed by the C compiler. If your pro- 
gram exceeds one of these limits, an error message will inform you of the 
problem. 


Table D.1 

Limits Imposed by the C Compiler 

Program Item Description Limit 
String literals Maximum length of a string, 512 bytes 


including the terminating null 
character (\ 0) 


Constants Maximum size of a constant is 
determined by its type; see 
the Microsoft C Language 
Reference for a discussion of 


constants. 
Identifiers Maximum length of an 31 bytes (additional 
identifier characters are 
discarded) 
Declarations Maximum level of nesting for 10 levels 
structure/union definitions 
Preprocessor Maximum size of a macro 512 bytes 
directives definition 
Maximum number of actual 8 arguments 
arguments to a macro 
definition 
Maximum length of an actual 256 bytes 
preprocessor argument 
Maximum level of nesting for 32 levels 
# if, # ifdef, and # ifndef 
directives 
Maximum level of nesting for 10 levels 


include files 
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Error-Message Reference 


The compiler does not set explicit limits on the number and complexity of 
declarations, definitions, and statements in an individual function or in a 
program. If the compiler encounters a function or program that is too 
large or too complex to be processed, it produces an error message to that 
effect. 


D.2 Command-Line Error Messages 


Messages that indicate errors on the command line used to invoke the 
compiler have one of the following formats: 


command line fatal error Dlzzz: messagetext Fatal error 
command line error D2zxz: messagetezt Error 
command line warning D4zrrz: messagetert Warning 


If possible, the compiler continues operation, printing a warning message. 
In some cases, command-line errors are fatal and the compiler terminates 
processing. The messages in Sections D.2.1—D.2.3 indicate errors on the 
command line. 


D.2.1 Command-Line 
Fatal-Error Messages 


The following messages identify fatal errors. The compiler driver cannot 
recover from a fatal error; it terminates after printing the error message. 


Number Command-Line Fatal-Error Message 

D1000 UNKNOWN COMMAND LINE FATAL ERROR Contact 
Microsoft Technical Support 
The compiler detected an unknown fatal-error condition. 


Please report this condition to Microsoft Corporation, 
using the Product Assistance Request form at the back of 
this manual. 


D1001 could not execute ‘/filename' 


The compiler could not find the given file in the current 
working directory or in any of the other directories named 


in the PATH variable. 
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D1002 


too many open files, cannot redirect 


" fillename' 
No more file handles were available to redirect the output 


of the /P option to a file. 
Try editing your CONFIG.SYS file and increasing the 


value num on the line files=num (if num is less than 20). 


D.2.2 Command-Line Error Messages 


When the compiler driver encounters any of the errors listed in this sec- 
tion, it continues compiling the program (if cee and outputs addi- 


tional error messages. However, no object file is pro 


Number 


D2000 


D2001 


D2002 


D2003 


D2007 
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uced. 
Command-Line Error Message 

UNKNOWN COMMAND LINE ERROR 

Contact Microsoft Technical Support 
The compiler detected an unknown error condition. 


Please report this condition to Microsoft Corporation, 
using the Product Assistance Request form at the back of 
this manual. 

too many symbols predefined with -D 


Too many symbolic constants were defined by using the /D 
option on the command line. 


The normal limit on command-line definitions is 16; you 
can use the /U or /u option to increase the limit to 20. 

a previously defined model specification 
has been overridden 

Two different memory models were specified; the model 
specified later on the command line was used. 

missing source file name 

You did not give the name of the source file to be compiled. 
bad option flag, would overwrite '‘stringi' with 
" stringe' 


The specified option was given more than once, with 
conflicting arguments sfringl and string2. 


Number 


D2008 


D2009 


D2010 


D2011 


D2012 


P2015 


D2018 


D2019 
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Command-Line Error Message 


too many option flags, 'string' 

Too many letters were given with the specified option (for 
example, with the /O option). 

unknown option character in ‘ optionstring' 


One of the letters in the given option was not recognized. 


unknown floating point option 

The specified floating-point option (an /FP option) was not 
one of the valid options. 

only one floating point model allowed 

You specified more than one floating-point (/FP) option on 
the command line. 

too many linker flags on command line 

You tried to pass more than 128 separate options and 
object files to the linker. 

assembly files are not handled 


You gave a file name with an extension of .ASM on the 
command line. 


Because the compiler cannot invoke the Microsoft Macro 
Assembler (MASM) automatically, it cannot assemble such 
files. 


cannot open linker cmd file 


The response file used to pass object-file names and options 
to the linker could not be opened. 


This error may have occurred because another read-only file 
had the same name as the response file. 

cannot overwrite the source file, 'name' 

You specified the source file as an output-file name. 


The compiler does not allow the source file to be overwrit- 
ten by one of the compiler output files. 
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Number 


D2020 


D2021 


D2022 


Command-Line Error Message 
-Gc option requires extended keywords to be 
enabled (-Ze) 


The /Ge option and the /Za option were specified on the 
same command line. 


The ( Ge option requires the extended keyword cdecl to be 
enabled if library functions are to be accessible. 

invalid numerical argument ' string’ 

A non-numerical string was specified following an option 
that required a numerical argument. 

cannot open help file, cl.hlp 


The /HELP option was given, but the file containing the 
help messages (QCL.HLP) was not in the current directory 
or in any of the directories specified by the PATH environ- 
ment variable. 


D.2.3 Command-Line Warning Messages 


The messages listed in this section indicate potential problems, but the 
errors do not hinder compilation and linking. 


Number 


D4000 


D4002 


D4003 
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Command-Line Warning Message 
UNKNOWN COMMAND LINE WARNING 
Contact Microsoft Technical Support 


An unknown command-line error condition has been de- 
tected by the compiler. 


Please report this condition to Microsoft Corporation, 
using the Product Assistance Request form at the back of 
this manual. 


ignoring unknown flag 'string' 

One of the options given on the command line was not 
recognized and is ignored. 

80186/286 selected over 8086 for code 
generation 


Both the /GO option and the /G2 option were given; /G2 
takes precedence. 


Number 


D4004 


D4005 


D4006 


D4007 


D4009 


D4010 


D4013 


D4014 


D4017 
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Command-Line Warning Message 


optimizing for time over space 

This message confirms that the /Ot option is used for 
optimizing. 

could not execute 'filename'; please insert 
diskette and press any key 

The QCL command could not find the specified executable 
file in the search path. 

only one of -P/-E/-EP allowed, -P selected 
More than one preprocessor output option was specified. 
-C ignored (must also specify -P or ~-E or 
-EP) 

The /C option must be used in conjunction with one of the 
preprocessor output flags, /E, /EP, or /P. 

threshold only for far/huge data, ignored 


The /Gt option was used in a memory model that has near 
data pointers. It can be used only in compact and large 
models. 


-Gp not implemented, ignored 

The DOS version of Microsoft C does not support profiling. 
combined listing has precedence over object 
listing 

When /Fc is specified along with either /Fl or /Fa, the 
combined listing (/Fc) is created. 

invalid value number for '‘'string'. Default 
number is used 

An invalid value was given in a context where a particular 
numeric value was expected. 

conflicting stack checking options ~- stack 
checking disabled 


You gave both the /Ge and the /Gs options on the CL 
command line. The /Gs option takes precedence, so stack 
checking is disabled in the program. 
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D.3 Run-Time Error Messages 


Run-time error messages fall into four categories: 


1. Floating-point exceptions generated by the 8087 /80287 hardware 
or the emulator. These exceptions are listed and described in Sec- 
tion D.3.1. 


2. Error messages generated by the run-time library to notify you of 
serious errors. These messages are listed and described in Section 
D.3.2. 


3. Error messages generated by program calls to error-handling rou- 
tines in the C run-time hbrary—the abort, assert, and perror 
routines. These routines print an error message to standard error 
output whenever the program calls the given routine. For descrip- 
tions of these routines and the corresponding error messages, see 
the Microsoft C Run-Time Library Reference . 


4. Error messages generated by calls to math routines in the C run- 
time library. On error, the math routines return an error value and 
some print a message to the standard error output. See the Aficro- 
soft C Run-Time Library Reference for descriptions of the math 
routines and corresponding error messages. 


D.3.1 Floating-Point Exceptions 


The error messages listed below correspond to exceptions generated by the 
8087 /80287 hardware. Refer to the Intel documentation for your processor 
for a detailed discussion of hardware exceptions. These errors may also be 
detected by the floating-point emulator built into the standard QuickC 
library. 


Using C’s default 8087 /80287 control-word settings, the following excep- 
tions are masked and do not occur: 


Exception Default Masked Action 
Denormal Exception masked 
Underflow Result goes to 0.0 
Inexact Exception masked 


For information on how to change the floating-point control word, see the 
reference pages for _control87 in the Microsoft C Run-Time Library 
Reference . 
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The following errors do not occur with code generated by the Microsoft 
QuickC Compiler or provided in the standard C library: 


Square root 
Stack underflow 
Unemulated 


The floating-point exceptions have the following format: 


run-time error M61lnn: MATH 
- floating-point error: messagetext 


The floating-point exceptions are listed and described below: 
Number Floating-Point Exception 


M6101 invalid 


An invalid operation occurred. These usually involve 
operating on NANs or infinities. This error terminates the 
program with exit code 129. 


M6102 denormal 


A very small floating-point number was generated and may 
no longer be valid due to loss of significance. Denormals are 
normally masked, causing them to be trapped and operated 
on. This error terminates the program with exit code 130. 


M6103 divide by 0 
An attempt was made to divide by 0. This error terminates 
the program with exit code 131. 

M6104 over flow 
An overflow occurred in a floating-point operation. This 
error terminates the program with exit code 132. 

M6105 under flow 


An underflow occurred in a floating-point operation. (An 
underflow is normally masked so that the underflowing 
value is replaced with 0.0.) This error terminates the pro- 
gram with exit code 133. 


M6106 inexact 


Loss of precision occurred in a floating-point operation. 
This exception is normally masked since almost any 
floating-point operation can cause loss of precision. This 
error terminates the program with exit code 134. 
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Number 


M6107 


M6108 


M6110 


Mo111 


M6112 


Floating-Point Exception 


unemulated 


An attempt was made to execute an 8087/80287 instruction 
that is invalid or not supported by the emulator. This error 
terminates the program with exit code 135. 


square root 


The operand in a square-root operation was negative. This 
error terminates the program with exit code 136. (Note: the 
sqrt function in the C run-time library checks the argu- 
ment before performing the operation and returns an error 
value if the operand is negative; see the Microsoft C Run- 
Time Library Reference for details on sqrt.) 


stack overflow 


A floating-point expression caused a stack overflow on the 
8087 or 80287 coprocessor or the emulator. (Stack-overflow 
exceptions are trapped up to a limit of seven levels in addi- 
tion to the eight levels normally supported by the 8087 or 
80287 coprocessor.) This error terminates the program with 
exit code 138. 


stack underflow 


A floating-point operation resulted in a stack underflow on 
the 8087 or 80287 coprocessor or the emulator. This error 
terminates the program with exit code 139. 


explicitly generated 


A signal indicating a floating-point error was sent using a 
raise (SIGEFPE) call. This error terminates the program 
with exit code 140. 


D.3.2 Run-Time-Library Error Messages 


The following messages may be generated at run time when your program 
has serious errors. Run-time error-message numbers range from R6000 to 


R6999. 


A run-time error message takes the following general form: 


run-time error R6nnn 


- messagetert 


3680 


Number 


R6000 


R6001 


R6002 


Error-Message Reference 


Run-Time-Library Error Message 


stack overflow 


Your program has run out of stack space. This can occur 
when a program uses a large amount of local data or is 
heavily recursive. The program was terminated with an exit 
code of 255. 


To correct the problem, recompile using the /F option of 
the QCL command or relink using the linker /STACK 
option to allocate a large stack. 


null pointer assignment 


The contents of the NULL segment have changed in the 
course of program execution. The NULL segment is a spe- 
cial location in low memory that is not normally used. If 
the contents of the NULL segment change during a pro- 
gram’s execution, it means that the program has written to 
this area, usually by an inadvertent assignment through a 
null pointer. Note that your program can contain null 
pointers without generating this message; the message 
appears only when you access a memory location through 
the null pointer. 


This error does not cause your program to terminate; the 
error message is printed following the normal termination 
of the program. This error yields a nonzero exit code. 


This message reflects a potentially serious error in your pro- 
gram. Although a program that produces this error may 
appear to operate correctly, it is hkely to cause problems in 
the future and may fail to run in a different operating 
environment. 


floating point not loaded 


Your program needs the floating-point library, but the 
library was not loaded. The error causes the program to be 
terminated with an exit status of 255. This occurs in two 
situations: 


1. The program was compiled or linked with an option 
(such as /FPi87) that required an 8087 or 80287 
coprocessor, but the program was run on a machine 
that did not have a coprocessor installed. To fix this 
problem, either recompile the program with the 
/F Pi option or install a coprocessor. (See Section 
9.3.5 of this manual for more information about 
these options and libraries.) 
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Number 


R6003 


R6004 


R6005 


R6006 


R6007 
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Run-Time-Library Error Message 


2. A format string for one of the routines in the printf 
or scanf families contains a floating-point format 
specification and there are no floating-point values 
or variables in the program. The QuickC compiler 
attempts to minimize the size of a program by load- 
ing floating-point support only when necessary. 
Floating-point format specifications within format 
strings are not detected, so the necessary floating- 
point routines are not loaded. To correct this error, 
use a floating-point argument to correspond to the 
floating-point format specification. This causes 
floating-point support to be loaded. 


integer divide by 0 


An attempt was made to divide an integer by 0, giving an 
undefined result. This error terminates the program with an 
exit code of 255. 


DOS 2.0 or later required 


The QuickC compiler cannot run on versions of DOS prior 
to 2.0. 


not enough memory on exec 


Errors R6005 through R6007 occur when a child process 
spawned by one of the exec library routines fails, and DOS 
could not return control to the parent process. This error 
indicates that not enough memory remained to load the 
program being spawned. 


bad format on exec 

The file to be executed by one of the exec functions was 
not in the correct format for an executable file. 

bad environment on exec 


During a call to one of the exee functions, DOS determined 
that the child process was being given a bad environment 
block. 


Number 
R6008 


R6009 


R6012 


R6013 


R6015 


Error-Message Reference 


Run-Time-Library Error Message 
not enough space for arguments 


not enough space for environment 


Errors R6008 and R6009 both occur at start-up if there is 
enough memory to load the program, but not enough room 
for the argu vector, the envp vector, or both. To avoid this 
problem, rewrite the _setargv or _setenvp routines. 


Invalid near pointer reference 
A null near pointer was used in the program. 


This error occurs only if pointer checking is in effect (that 
is, if the program was compiled with the Pointer Check 
option in the Compile dialog box, the /Zr option on the 
QCL command line, or the pointer_ check pragma in 
effect). 


Invalid far pointer reference 
An out-of-range far pointer was used in the program. 


This error occurs only if pointer checking is in effect (that 
is, if the program was compiled with the Pointer Check 
option in the Compile dialog box, the /Zr option on the 
oe line, or the pointer_ check pragma in 
eflect). 


unexpected interrupt 


The program could not be run because it contained unex- 
pected interrupts. 


When it creates an in-memory program from a program 
list, QuickC automatically creates object files and passes 
them to the linker. The object files that QuickC passes to 
the linker contain interrupts that are required within the 
QuickC environment. However, you cannot run a program 
created from such object files outside of the QuickC pro- 
gramming environment. 


D.3.3. Run-Time Limits 


Table D.2 summarizes the limits that apply to programs at run time. If 
your program exceeds one of these limits, an error message will inform you 
of the problem. 
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Table D.2 

Program Limits at Run Time 

Item Description Limit 

Files Maximum file size 2°2_ 1 bytes 

(4 gigabytes) 

Maximum number 20° 
of open files (streams) 

Command line Maximum number of 128 


characters (including 
program name) 


Environment Maximum size 32h 
table 


4 Five streams are opened automatically (stdin, stdout, stderr, stdaux, and 
stdprn), leaving 15 files available for the program to open 


D.4_ LINK Error Messages 


This section lists and describes error messages generated by the Microsoft 


Overlay Linker, LINK. 


Fatal errors cause the linker to stop execution. Fatal error messages have 
the following format: 


location: fatal error Llarar: messagetext 


Nonfatal errors indicate problems in the executable file. LINK produces 
the executable file. Nonfatal error messages have the following format: 


location: error L2arxr: messagetezt 


Warnings indicate possible problems in the executable file. LINK pro- 
duces the executable file. Warnings have the following format: 


location : warning L4rraz: messagetext 


In these messages, location is the input file associated with the error, or 
LINK if there is no input file. If the input file is an .OBJ or .LIB file and 
has a module name, the module name is enclosed in parentheses, as shown 
in the following examples: 


SLIBC.LIB(_file) 
MAIN.OBJ (main.c) 
TEXT .OBJ 
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Error-Message Reference 


Linker errors may occur when you invoke the linker implicitly with the 
QCL command or explicitly with the LINK command. They may also 
occur when you compile a program that has a program list, or when you 
create an executable file on disk, within the QuickC environment. If linker 
errors occur within the QuickC programming environment, QuickC 
displays this message: 


Errors during link phase 
No .EXE file produced 


To view the linker errors, press ENTER or click the OK command button. 
The errors for the most recent linker pass are stored in a file named 


LINK.ERR. 


The error messages listed in this section may appear when you link object 
files with the Microsoft Overlay Linker, LINK. 


Number LINK Error Message 


L1001 option : option name ambiguous 
A unique option name did not appear after the option indi- 
cator (/) For example, the command 


LINK /N main; 


generates this error, since LINK cannot tell which of the 

three options beginning with the letter “N” was intended. 
L1002 option : unrecognized option name 

An unrecognized character followed the option indicator 

(/), as in the following example: 


LINK /ABCDEF main; 


L1004 option : invalid numeric value 


An incorrect value appeared for one of the linker options. 
For example, a character string was given for an option 
that requires a numeric value. 


L1006 option : stack size exceeds 65535 bytes 
The size specified for the stack was more than 65,535 bytes. 


L1007 option : interrupt number exceeds 255 


A number greater than 255 was given as a value for the 


/OVERLAYINTERRUPT option. 
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Number LINK Error Message 


L1008 option : segment limit set too high 
The limit on the number of segments allowed was set to 
greater than 3072 through use of the /SEGMENTS 
option. 

L1009 option : CPARMAXALLOC : illegal value 
The number specified in the /CPARMAXALLOC option 
was not in the range 1-65,535. 

L1020 no object modules specified 


No object-file names were specified to the linker. 


L1021 cannot nest response files 


A response file occurred within a response file. 


L1022 response line too long 


A line in a response file was longer than 127 characters. 


L1023 terminated by user 
You entered CONTROL+C 


L1024 nested right parentheses 


The contents of an overlay were typed incorrectly on the 
command line. 


L1025 nested left parentheses 


The contents of an overlay were typed incorrectly on the 
command line. 


L1026 unmatched right parenthesis 


A right parenthesis was missing from the contents speci- 
fication of an overlay on the command line. 


L1027 unmatched left parenthesis 


A left parenthesis was missing from the contents speci- 
fication of an overlay on the command line. 
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Number 


L1043 


L1045 


L1046 


L1047 


L1048 


L1049 


Error-Message Reference 


LINK Error Message 


relocation table overflow 


More than 32,768 long calls, long jumps, or other long 
pointers appeared in the program. 


Try replacing long references with short references, where 
possible, and recreating the object module. 
too many TYPDEF records 


An object module contained more than 255 TYPDEF 
records. These records describe communal variables. This 
error can appear only with programs produced by the 
Microsoft QuickC Compiler or other compilers that support 
communal variables. (TYPDEF is a DOS term. It is 
explained in the Microsoft MS-DOS Programmer’s Reference 
and in other reference books on DOS.) 

too many external symbols in one module 


An object module specified more than the limit of 1023 
external symbols. 


Break the module into smaller parts. 
too many group, segment, and class names 
in one module 


The program contained too many group, segment, and class 
names. 


Reduce the number of groups, segments, or classes, and 
recreate the object file. 

too many segments in one module 

An object module had more than 255 segments. 


Split the module or combine segments. 


too many segments 


The program had more than the maximum number of seg- 
ments. (The /SEGMENTS option specifies the maximum 
legal number; the default is 128.) 


Relink using the /SEGMENTS option with an appropri- 
ate number of segments. 


367 


Microsoft QuickC Compiler Programmer’s Guide 


Number 


L1050 


L1i051 


L1052 


Is 1OS3 


L1054 


L1056 
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LINK Error Message 


too many groups in one module 


LINK encountered more than 21 group definitions 


(GRPDEF) in a single module. 


Reduce the number of group definitions or split the module. 
Group definitions are explained in the Aficrosoft M[S-DOS 

rograminer’s Reference and in other DOS reference books.) 
too many groups 


The program defined more than 20 groups, not counting 
DGROUP. 


Reduce the number of groups. 


too many libraries 

An attempt was made to link with more than 32 libraries. 
Combine libraries, or use modules that require fewer 
libraries. 

symbol table overflow 


The linker did not have enough memory to accommodate 
the symbolic information of the program (such as public, 
external, segment, group, class, and file names). 


Combine modules or segments and recreate the object files. 
Eliminate as many public symbols as possible. 


requested segment limit too high 


The linker did not have enough memory to allocate tables 
describing the number of segments requested. (The default 
is 128 or the value specified with the /SEGMENTS 
option.) 

Try linking again using the /SEGMENTS option to select 
a smaller number of segments (for example, use 64 if the 
default was used previously), or free some memory by elim- 
inating resident programs or shells. 


too many overlays 


The program defined more than 63 overlays. 


Number 


L1057 


L1070 


L1i071 


L1072 


L1080 


L1081 


Error-Message Reference 


LINK Error Message 


data record too large 


A LIDATA record (in an object module) contained more 
than 1024 bytes of data. This is a translator error. 
LIDATA is a DOS term, explained in the Microsoft MS- 

OS Programmer’s Reference and in other DOS reference 
books.) 


Note which translator (compiler or assembler) produced the 
incorrect object module and what the circumstances were. 
Please report this error using the Product Assistance Re- 
quest form at the back of this manual. 

name: segment size exceeds 64K 


The specified segment contained more than 64K of code or 
data. 


Try compiling and linking using the large model. 


segment _TEXT larger than 65520 bytes 


This error is likely to occur only in small-model C pro- 
grams, but it can occur when any program with a segment 
named — TEXT is linked by using the /DOSSEG option 
of the LINK command. Small-model C programs must 
reserve code addresses 0 and 1; this range is increased to 16 
for alignment purposes. 

common area longer than 65536 bytes 


The program had more than 64K of communal variables. 
This error cannot appear with object files generated by the 
Microsoft Macro Assembler, MASM. It occurs only with 
programs produced by the Microsoft QuickC Compiler or 
other compilers that support communal variables. 


cannot open list file 
The disk or the root directory was full. 


Delete or move files to make space. 


out of space for run file 
The disk on which the .EXE file was being written was full. 


Free more space on the disk and restart the linker. 
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Number 


1083 


L1i084 


L1085 


L1086 


L1087 


L1088 


L1089 


L1090 


L1og1 


370 


LINK Error Message 


cannot open run file 
The disk or the root directory was full. 


Delete or move files to make space. 


cannot create temporary file 
The disk or root directory was full. 


Free more space in the directory and restart the linker. 


cannot open temporary file 
The disk or the root directory was full. 


Delete or move files to make space. 


scratch file missing 

An internal error occurred. 

Note the circumstances of the problem and contact Micro- 
soft Corporation, using the Product Assistance Request 
form at the back of this manual. 

unexpected end-of-file on scratch file 

The disk with the temporary linker-output file was 
removed. 

out of space for list file 


The disk on which the listing file was being written was 


full. 


Free more space on the disk and restart the linker. 


filename : cannot open response file 


LINK could not find the specified response file. This usu- 
ally indicates a typing error. 

cannot reopen list file 

The original disk was not replaced at the prompt. 
Restart the linker. 


unexpected end-of~-file on library 
The disk containing the library probably was removed. 


Replace the disk containing the library and run the linker 
again. 


Number 


ELO93 


DLtOL 


L1102 


Li103 


L1i104 


La 3 


L1114 


Error-Message Reference 


LINK Error Message 


filename: object not found 
The linker could not find the given object file. 


Restart the linker and specify the correct object-file name. 


invalid object module 
One of the object modules was invalid. 


If the error persists after recompiling, please contact Micro- 
soft Corporation, using the Product Assistance Request 
form at the back of this manual. 


unexpected end-of-file 

An invalid format for a library was encountered. 
attempt to access data outside segment 
bounds 


A data record in an object module specified data extending 
beyond the end of a segment. This is a translator error. 


Note which translator (compiler or assembler) produced the 
incorrect object module and the circumstances in which it 
was produced. Please report this error to Microsoft Cor- 
poration, using the Product Assistance Request form at the 
back of this manual. 


filename : not valid library 

The specified file was not a valid library file. This error 
causes LINK to abort. 

unresolved COMDEF; internal error 


Note the circumstances of the failure and contact Microsoft 
Corporation, using the Product Assistance Request form at 
the back of this manual. 


file not suitable for /EXEPACK; relink 
without 


For the linked program, the size of the packed load image 
plus packing overhead was larger than that of the un- 
packed load image. 


Relink without the /EXEPACK option. 
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Number 


L2001 


L2002 


372 


LINK Error Message 


fixup(s) without data 


A FIXUPP record occurred without a data record immedi- 
ately preceding it. This is probably a compiler error. (See 
the Microsoft MS-DOS Programmer’s Reference for more 
information on FIXUPP.) 


fixup overflow at number in frame seg segname 
target seg segname target offset number 


The following conditions can cause this error: 


A small-model program is compiled with the /NT 
option. 


A group is larger than 64K. 


The program contains an intersegment short jump 
or intersegment short call. 


The name of a data item in the program conflicts 
with that of a subroutine in a library included in 
the link. 


An EXTRN declaration in an assembly-language 
source file appeared inside the body of a segment, as 
in the following example: 


code SEGMENT public 'CODE' 
EXTRN main: far 
start PROC far 
call main 
ret 
start ENDP 
code ENDS 


The following construction is preferred: 


EXTRN main: far 
code SEGMENT public 'CODE' 
start PROC far 

call main 

ret 
start ENDP 
code ENDS 


Revise the source file and recreate the object file. 
(For information about frame and target segments, 
refer ‘i the Aficrosoft MS-DOS Programmer’s Refer- 
ence. 


Number 


L2003 


L2005 


L2012 


L2013 


L2024 


L2025 


L2029 


Error-Message Reference 


LINK Error Message 


intersegment self-relative fixup 


An intersegment self-relative fixup is not allowed. 


fixup type unsupported 


A fixup type occurred that is not supported by the Micro- 
soft linker. This is probably a compiler error. 


Note the circumstances of the failure and contact Microsoft 
Corporation using the Product Assistance Request form at 
the back of this manual. 


"name' : array-element size mismatch 


A far communal array was declared with two or more 
different array-element sizes (for example, an array was 
declared once as an array of characters and once as an 
array of real numbers). 


LIDATA record too large 


A LIDATA record in an object module was larger than 512 
bytes, the maximum legal size. This is a compiler error. 


Please report this condition by using the Product Assis- 
tance Request form at the back of this manual. 

name : symbol already defined 

One of the special overlay symbols required for overlay sup- 
port was defined by an object. 

‘name’ :; symbol defined more than once 


Remove the extra symbol definition from the object file. 


Unresolved externals 


One or more symbols were declared to be external in one or 
more modules, but they were not publicly defined in any of 
the modules or libraries. A list of the unresolved external 
references appears after the message, as shown in the fol- 
lowing example: 


EXIT in file(s): 
MAIN.OBJ (main. for) 
OPEN in file(s): 
MAIN.OBJ (main. for) 
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Number 


L2041 


L2043 


L4003 


L4012 


L4015 


L4016 


L4020 


374 


LINK Error Message 


The name that comes before in file(s) is the unre- 
solved external symbol. On the next line is a list of object 
modules that have made references to this symbol. This 
message and the list are also written to the map file, if one 
exists. 


stack plus data exceed 64K 


The combined size of the program stack segment plus 
DGROUP was greater than 64Kx; as a result, the program 
will not load correctly. 


starting address __aulstart not found 


When you build a Quick library using the /Q option, the 
linker expects to find the symbol __ aulstart defined as a 
starting address. 


intersegment self-relative fixup at offset in 
segment name pos: offset Record type: 9C target 
external 


The linker found an intersegment self-relative fixup. This 
error may be caused by compiling a small-model program 


with the /NT option. 

load-high disables EXEPACK 

The /HIGH and /EXEPACK options cannot be used at 
the same time. 

/CODEVIEW disables /DSALLOCATE 

The /CODEVIEW and /DSALLOCATE options can- 
not be used at the same time. 

/CODEVIEW disables /EXEPACK 

The /CODEVIEW and /EXEPACK options cannot be 


used at the same time. 


name : code-segment size exceeds 65500 


Code segments of 65,501-65,536 bytes in length may be 
unreliable on the Intel 80286 processor. 


Number 


L4021 


L4031 


L4034 


L4045 


L4050 


Lh4051 


Error-Message Reference 


LINK Error Message 


no stack segment 


The program did not contain a stack segment defined with 
STACK combine type. This message should not appear for 
modules compiled with the Microsoft QuickC Compiler, but 
it could appear for an assembly-language module. 


Normally, every program should have a stack segment with 
the combine type specified as STACK. You can ignore 
this message if you have a specific reason for not defining a 
stack or for defining one without the STACK combine 
type. Linking with versions of LINK earlier than 2.40 
might cause this message, since these linkers search li- 
braries only once. 


name : segment declared in more than one 
group 


A segment was declared to be a member of two different 
groups. 


Correct the source file and recreate the object files. 

more than 239 overlay segments; extra put 
in root 

No more than 239 code segments can be defined in overlays. 
Any segments over this limit are assigned to the root. 

name of output file is name 


The linker displayed a default output-file name in the “Run 
file’ prompt but changed the output-file name because the 
/Q option was used. 

too many public symbols 


The /MAP option was used to request a sorted listing of 
public symbols in the map file, but there were too many 
symbols to sort (more than 2048 symbols by default). 


Relink using /MAP:number. The linker produces an 
unsorted listing of the public symbols. 


filename : cannot find library 
The linker could not find the specified file. 


Inter a new file name, a new path specification, or both. 
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Number LINK Error Message 


L4053 VM.TMP : illegal file name; ignored 
VM.TMP appeared as an object-file name. 


Rename the file and rerun the linker. 


L4054 filename : cannot find file 
The linker could not find the specified file. 


Enter a new file name, a new path specification, or both. 


D.5 LIB Error Messages 


Error messages generated by the Microsoft Library Manager, LIB, have 
one of the following formats: 


{ filename| LIB} : fatal error Ulgrr: messagetext 
{ filename| LIB} : error U2sazr: messagetezt 
{ filename| LIB} : warning U4zarr: messagetext 


The message begins with the input-file name (filename), if one exists, or 
with the name of the utility. If possible, LIB prints a warning and contin- 
ues operation. In some cases errors are fatal and LIB terminates process- 
ing. LIB may display the following error messages: 


Number LIB Error Message 


ULLSO page size too small 
The page size of an input library was too small, which indi- 
cates an invalid input .LIB file. 

U1151 syntax error : illegal file specification 
A command operator such as a minus sign (—) was given 
without a following module name. 

ULiss syntax error : option name missing 


A forward slash (/) was given without a following option. 
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Number 


ULLSS 


U1154 


ULL 


UlLS6 


UlLTS7 


ULISS 


Utd. 


Error-Message Reference 


LIB Error Message 


syntax error : option value missing 

The /PAGESIZE option was given without a value fol- 
lowing it. 

option unknown 

An unknown option was given. Currently, LIB only recog- 
nizes the /PAGESIZE option. 

syntax error : illegal input 


The given command did not follow correct LIB syntax as 
specified in Chapter 10, “Creating Quick Libraries and 
Stand-Alone Libraries.” 

syntax error 


The given command did not follow correct LIB syntax as 
specified in Chapter 10, “Creating Quick Libraries and 
Stand-Alone Libraries.” 

comma or new line missing 


A comma or carriage return was expected in the command 
line but did not appear. This may indicate an inappropri- 
ately placed comma, as in the following line: 


LIB math.lib, -mod1l+mod2; 
The line should have been entered as follows: 
LIB math.lib -mod1l+mod2: 


terminator missing 


Either the response to the “Output library” prompt or the 
last line of the response file used to start LIB did not end 
with a carriage return. 


cannot rename old library 


LIB could not rename the old library to have a .BAK 
extension because the .BAK version already existed with 
read-only protection. 


Change the protection on the old .BAK version. 
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Number 


U1162 


ULIGsS 


U1170 


Gb Binge 


U1172 


ULL7TS 


U1174 


ULL/S 


U1180 


378 


LIB Error Message 


cannot reopen library 

The old library could not be reopened after it was renamed 
to have a .BAK extension. 

error writing to cross-reference file 

The disk or root directory was full. 


Delete or move files to make space. 


too many symbols 
More than 4609 symbols appeared in the library file. 


insufficient memory 

LIB did not have enough memory to run. 

Remove any shells or resident programs and try again, or 
add more memory. 

no more virtual memory 


Note the circumstances of the failure and notify Microsoft 
Corporation, using the Product Assistance Request form at 
the back of this manual. 

internal failure 


Note the circumstances of the failure and notify Microsoft 
Corporation, using the Product Assistance Request form at 
the back of this manual. 

mark: not allocated 


Note the circumstances of the failure and notify Microsoft 
Corporation, using the Product Assistance Request form at 
the back of this manual. 

free: not allocated 


Note the circumstances of the failure and notify Microsoft 
Corporation, using the Product Assistance Request form at 
the back of this manual. 

write to extract file failed 

The disk or root directory was full. 


Delete or move files to make space. 


Number 


ULTS1. 


ULLe2 


ULle3 


U1184 


ULISS 


U1186 


U1187 


U1188 


Error-Message Reference 


— 7 


LIB Error Message 


write to library file failed 
The disk or root directory was full. 


Delete or move files to make space. 


filename : cannot create extract file 


The disk or root directory was full, or the specified extract 
file already existed with read-only protection. 


Make space on the disk or change the protection of the ex- 
tract file. 
cannot open response file 


The response file was not found. 


unexpected end-of-file on command input 
An end-of-file character was received prematurely in 
response to a prompt. 

cannot create new library 


The disk or root directory was full, or the library file al- 
ready existed with read-only protection. 


Make space on the disk or change the protection of the 
library file. 

error writing to new library 

The disk or root directory was full. 


Delete or move files to make space. 


cannot open VM.TMP 
The disk or root directory was full. 


Delete or move files to make space. 


cannot write to VM 


Note the circumstances of the failure and notify Microsoft 
Corporation, using the Product Assistance Request form at 
the back of this manual. 
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Number 


U1189 


UL190 


U1200 


U1203 


U2Z152 


U2155 


U2157 


U2158 


U2b59 


380 


LIB Error Message 


cannot read from VM 

Note the circumstances of this error and notify Microsoft 
Corporation, using the Product Assistance Request form at 
the back of this manual. 

interrupted by user 

You terminated the LIB session before it had finished exe- 
cution. 

name : invalid library header 

The input library file had an invalid format. It was either 
not a library file, or it had been corrupted. 

name : invalid object module near location 
The module specified by name was not a valid object 
module. 

filename : cannot create listing 


The directory or disk was full, or the cross-reference-listing 
file already existed with read-only protection. 


Make space on the disk or change the protection of the 
cross-reference-listing file. 
modulename : module not in library; ignored 


The specified module was not found in the input library. 


filename : cannot access file 

LIB was unable to open the specified file. 

libraryname : invalid library header; file 
ignored 

The input library had an incorrect format. 

filename : invalid format hernumber; file 
ignored 


The signature byte or word hernumber of the given file was 
not one of the following recognized types: Microsoft library, 
Intel library, Microsoft object, or XENIX archive. 


Number 


U4150 


U4151 


U4153 


U4156 


Error-Message Reference 


LIB Error Message 


modulename : module redefinition ignored 


A module was specified to be added to a library but a mo-~ 
dule with the same name was already in the library. Or, a 
module with the same name was found more than once in 
the library. 


symbol(modulename) : symbol redefinition 
ignored 


The specified symbol was defined in more than one module. 


number : page size too small; ignored 

The value specified in the /PAGESIZE option was less 
than 16. 

libraryname : output-library specification 
ignored 

An output library was specified in addition to a new library 
name. For example, specifying 


LIB new. libtone.obj,new.lst,new.lib 


where new. lib does not already exist causes this error. 


D.6 MAKE Error Messages 


Error messages displayed by the Microsoft Program Maintenance Utility, 
MAKE, have one of the following formats: 


{ filename | MAKE} : fatal error Ulazr: messagetezt 
{ filename | MAKE} : warning U4zrrr: messagetezt 


The message begins with the input file name (filename), if one exists, or 
with the name of the utility. If possible, MAKE prints a warning and con- 
tinues operation. In some cases, errors are fatal and MAKE terminates 
processing. MAKE generates the error messages listed in this section. 
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Number 


U1O001 


U1LO002 


U1003 


U1004 


U1005 


U1006 


382 


MAKE Error Message 


macro definition larger than number 


A single macro was defined to have a value string longer 
than the number stated, which is the maximum length 
allowed. 


Try rewriting the MAKE description file to split the macro 
into two or more smaller ones. 


infinitely recursive macro 


A circular chain of macros was defined, as in the following 
example: 


A=$ (B) 
B=$ (C) 
C=$ (A) 


out of memory 


MAKE ran out of memory for processing the MAKE 
description file. 


Try to reduce the size of the MAKE description file by 
reorganizing or splitting it. 


syntax error : macro name missing 


The MAKE description file contained a macro definition 
with no left side (that is, a line beginning with =). 


syntax error : colon missing 


A line that should be an outfile/infile line lacked a colon 
indicating the separation between outfile and infile.e MAKE 
expects any line following a blank line to be an outfile/infile 
line. 


targetname : macro expansion larger than 
number 


A single macro expansion, plus the length of any string to 
which it may be concatenated, was longer than the number 
stated. 


Try rewriting the MAKE description file to split the macro 
into two or more smaller ones. 


Number 


U1007 


U1008 


U1LOO9 


ULGLO 


ULOL 1 


U1012 


ULOLS 


ULOL5 


U4000 


Error-Message Reference 


MAKE Error Message 


multiple sources 


An inference rule was defined more than once. 


name : cannot find file or directory 


The file or directory specified by name could not be found. 


command : argument list too long 


A command line in the MAKE description file was longer 
than 128 bytes, which is the maximum that DOS allows. 


Rewrite the commands to use shorter argument lists. 


filename : permission denied 


The file specified by filename was a read-only file. 


filename : not enough memory 


Not enough memory was available for MAKE to execute a 
program. 


filename : unknown error 


Note the circumstances of the failure and notify Microsoft 
Corporation, using the Product Assistance Request form at 
the back of this manual. 


command : error errcode 
One of the programs or commands called in the MAKE 
description file returned with a nonzero error code. 


file : error redirection failed 


You entered the MAKE command with the /x file option, 
but MAKE could not redirect error output to the given file 
(for example, because the file was read only). 


filename : target does not exist 


This usually does not indicate an error. It warns the user 
that the target file does not exist. MAKE executes any 
commands given in the block description, since in many 
cases the outfile will be created by a later command in the 


MAKE description file. 
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Number 


U4001 


U4013 


U4014 
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MAKE Error Message 


dependent filename does not exist; target 
filename not built 


MAKE could not continue because a required infile did not 
exist. 


Make sure that all named files are present and that they are 
spelled correctly in the MAKE description file. 


command : error errcode (ignored) 


One of the programs or commands called in the MAKE 
description file returned with a nonzero error code, and 
MAKE was run with the /I option. MAKE ignores the 
error and continues. 


usage : make options [name-value ...] file 
options = [/n} [/d] [/i] [/s] [/x file] 
MAKE has not been invoked correctly. 


Try entering the command line again with the syntax 
shown in the message. 


(GLOSSARY 


The definitions in this glossary are intended primarily for use with this 
manual, the Microsoft C Language Reference, and the Microsoft C Run- 
Time Library Reference . Neither individual definitions nor the list of 
terms is comprehensive. 


8087 or 80287 coprocessor 


Intele hardware products that provide very fast and precise number 
processing. 


abstract declarator | 
A declarator without an identifier, consisting of a type and, optionally, 
one or more pointer, array, or function modifiers. 

active page 


The area in memory where graphics output is written. 


aggregate types 
Arrays, structures, and unions. 


alias 


One of several alternative names for the same memory location. 


alternate math library 


A model-dependent floating-point library that uses a subset of the 
Institute of Electrical and Electronics Engineers, Inc. (EEE) number 
format. Linking with this library results in the smallest, fastest pro- 
grams available without a coprocessor, but sacrifices some accuracy in 
results. 


animation 


The process of creating graphics images that move on the screen. 


ANSI (American National Standards Institute) 


The national institute responsible for defining programming-language 
standards to promote portability of these languages between different 
computer systems. 
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argument 


A value passed to a function. 


argument-type list 


In a function prototype, a list of abstract declarators, separated by 
commas, indicating the types of actual arguments in the function call. 
Used to make sure the actual arguments in the function call 
correspond to the formal parameters in the function definition. 

arge 
The traditional name for the first argument to the main function in a 
C source program. This argument is an integer specifying how many 
arguments are passed to the program from the command line. 

argv 
The traditional name for the second argument to the main function in 
a C source program. This argument is a pointer to an array of strings. 
Traditionally, the first string is the program name and each following 
string is an argument passed to the program from the command line. 

arithmetic conversion 
Conversion operations performed on items of integral and floating- 
point types used in expressions. 

arithmetic types 


Integral, enumeration, and floating-point data types. 


array 


A set of elements with the same type. 


ASCII (American Standard Code for Information Interchange) 


A set of 256 codes that many computers use to represent letters, digits, 
special characters, and other symbols. Only the first 128 of these codes 
are standardized; the remaining 128 are special characters that are 
defined by the computer manufacturer. 


associativity 


The precedence rules that apply when more than one operator is 
assigned to an operand. For example, in the expression «p++, the 
indirection operator (*) is applied before the unary increment operator 


(++) 
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background color 


The color on which all drawing and color display takes place. 


base name 
The portion of the file name that precedes the file-name extension. For 
example, samp is the base name of the file samp.c. 

batch file 
A text file containing DOS commands that can be invoked from the 
DOS command line. 

binary expression 


An expression consisting of two operands joined by a binary operator. 


binary operator 


An operator used in binary expressions. Binary operators in the C 
language are the multiplicative operators (* /), additive operators 
+ —), shift operators(<< >>), relational operators 


< > <= >= == !5), bitwise operators(& ! *), logical 
operators (&& !!), and the sequential-evaluation operator (,). 
block 


A sequence of declarations, definitions, and statements enclosed within 
braces ({}). 


bounding rectangle 


The rectangular area used to define certain graphics operations. 


child process 


A new process started by a currently running process. 


clipping 


The limiting of graphics displays to a particular region of the screen, 
known as the clipping region. 


clipping region 


The rectangular portion of the screen where graphics output occurs. 


color value 


A unique ordinal value representing a displayable color. 
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compact memory model 
A memory model that allows for more than one data segment and only 
one code segment. 

complex declarator | 
A declaration containing more than one array, pointer, or function 
modifier. 

constant expression 


Any expression that evaluates to a constant and may involve integer 
constants, character constants, floating-point constants, enumeration 
constants, type casts to integral and floating-point types, and other 
constant expressions. 


coordinate system 


A system used to identify a screen location relative to the horizontal 
and vertical axes. Text is positioned in a character-based row and 
column coordinate system. Graphics figures are positioned in a pixel- 
based row and column coordinate system. 


core library 
The library of standard C routines that is built into the QuickC pro- 
gramming interface. 

current position 


The coordinate location given by an (2, y) logical-coordinate pair that 
defines the pixel point where the next graphics operations will take 
place. 


current text position 


The coordinate location given by a (row, column) coordinate pair that 
defines the row and column point where graphics-based text operations 
will take place. 

declaration 


A construct that associates the name and the attributes of a variable, 
function, or type. 
declarator 


An identifier that can be modified with brackets ([]), asterisks (*), or 
parentheses (( )) to declare an array, pointer, or function type, respec- 
tively. 
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definition 
A construct that initializes and allocates storage for a variable, or that 
specifies the name, formal parameters, body, and the return type of a 
function. 

directive 
An instruction to the C preprocessor to perform a specific action on 
source-program text before compilation. 

DOS interface functions 
Run-time library routines that provide access to DOS interrupts and 
system calls. 

emulator 
A floating-point-math package that provides software emulation of the 
operations of a math coprocessor. 

enumeration set 


The set of legal values defined for an enumeration type. 


enumeration type 


A user-defined data type that specifies a particular set of legal values. 


environment table 


The part of DOS that stores environment variables and their values. 


environment variable 


A variable stored in the environment table that provides DOS with 
information (where to find executable files and library files, where to 
create temporary files, etc.). 

errorlevel code 


See exit code. 


escape sequence 


A specific combination, comprising a backslash (\) followed by a letter 
or combination of digits, which represents white-space and nongraphic 
characters within strings and character constants. 

exit code 


A code returned by a program to DOS indicating whether or not the 
program ran successfully. 
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expression 


A combination of operands and operators that yields a single value. 


external level 


The part of a C program outside of all function declarations. 


file handle 
A value returned by library functions that open or create files, used to 
refer to that file in later operations. 

file pointer 


A pointer that indicates the current position in an input or output 
stream. It is updated to reflect the new position each time a read or 
write operation takes place. 


fill mask 


An 8-by-8 array of bits, where each bit represents a pixel, that defines 
the mask to be used in filling figures. When a figure is filled, the fill 
mask is repeated over the entire area. If a bit in the array is a 1, the 
corresponding pixel in the figure is set to the current color. If a bit is 0, 
the corresponding pixel is unchanged. The default fill mask is NULL. 


filling 
The process of applying a fill mask to a specified area. 


foreground color 


A color used to display text and draw graphics images. 


formal parameters 
Variables that receive values passed to a function when the function is 
called. 

forward declaration 


A function declaration that establishes the attributes of a function so 
that it can be called before it is defined or called from a different 
source file. 


function 


A collection of declarations and statements returning a value that can 
be called by name. 


function body 


A compound statement containing the local variable declarations and 
statements of a function. 
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function call 


An expression that passes control and actual arguments (if any) to a 
function. 


function declaration 


A declaration that establishes the name, return type, and storage class 
of a function that is defined explicitly elsewhere in the program. 


function definition 


A definition that specifies a function’s name, its formal parameters, the 
declarations and statements that define what it does, and (optionally) 
its return type and storage class. 


function prototype 


A function declaration that includes a list of the names and types of 
formal parameters in the parentheses following the function name. 


fundamental data types 


A set of basic C data types, which includes all integer, character, 
floating-point, and enumeration types. 


global 
See lifetime; visibility. 
heap 


An area of memory set aside for dynamic allocation by a program. 


include file 


A text file that is merged into another text file through use of the 
# include preprocessor directive. 


internal level 


The parts of a C program within function declarations. 


keyword 


A word with a special, predefined meaning for the QuickC compiler. 
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large memory model 


A memory model that allows for more than one segment of code and 
more than one segment of data, but with no individual data items 
spanning a single segment. 

level 


See internal level; external level. 


library 


A file that stores related modules of compiled code. The linker extracts 
modules from the library and combines them with other program ob- 
ject modules to create executable program files. 


lifetime 


The period during program execution in which a variable or function 
exists. An item with a “local” lifetime (a “local item” ) has storage and 
a defined value only within the block where the item is defined or 
declared. 


line style 


A 16-bit array that defines the mask to be used in drawing lines. If a 
bit in the array is a 1, the corresponding pixel in the line is set to the 
current color. If a bit is 0, the corresponding pixel is unchanged. The 
default line style is OxFFFF (a solid line). 


linked list 


A data structure consisting of a list of entries, each of which includes a 
pointer to the next entry. 


local 


See lifetime; visibility. 


logical coordinates 


The coordinate system defined by the programmer. The logical- 
coordinate system origin can be positioned anywhere on the screen’s 
physical-coordinate system. The default logical-coordinate system is 
identical to the physical-coordinate system which places the coordi- 
nates of the origin (0,0) at the top-left corner of the screen. 


logical origin 


The origin given by the logical-coordinate pair (0,0). All subsequent 
graphics output is relative to the logical origin. 


392 


Glossary 


loop optimization 
Optimizations that reduce the amount of code executed for each loop 
iteration in a program. 

low-level input and output routines 
Run-time library routines that perform unbuffered, unformatted I/O 
operations. 

Ivalue 
An expression (such as a variable name) that refers to a memory loca- 
tion and is required as the left-hand operand of an assignment opera- 
tion or the single operand of a unary operator. 

macro 
An identifier defined in a #define preprocessor directive to represent 
another series of tokens. 

manifest constant 
An identifier defined in a #define preprocessor directive to represent a 
constant value. 

medium memory model 
A memory model that allows for more than one code segment and only 
one data segment. 

member 


One of the elements of a structure or union. 


memory model 


One of the models that specifies how memory is set up for program 

code and data. (See small memory model, medium memory 

model, compact memory model, large memory model, and huge 

memory model for descriptions of standard memory models.) 
multidimensional array 


An array of arrays. 


naming classes 


Categories that the language sets up to distinguish between the 
identifiers used for different kinds of items. 
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NAN 


An abbreviation that stands for “not a number.” The 8087 or 80287 
coprocessor generates NANs when the result of an operation can- 
not be represented in the IEEE format. For example, if you try to add 
two positive numbers whose sum is larger than the maximum value 
permitted by the processor, the coprocessor returns a NAN instead 
of the sum. 

new-line character 


The character used to mark the end of a line of a text file, or the 
escape sequence (\n) used to represent this character. In DOS “text 
mode,” carriage-return—line-feed (CR-LF) combinations are trans- 
lated into a single line-feed (LF) character on input, and line-feed char- 
acters are translated into carriage-return—line-feed combinations on 
output. 

null character 
The ASCII character encoded as the value 0, represented as the escape 
sequence (\0O) in a source file. 

null pointer 


A pointer to nothing, expressed as the integer value 0. 


object 


A region of memory that can be examined. A modifiable object can 
also have a value stored into it (that is, it can be altered as well as 
examined). 


object file 


A file containing relocatable machine code, created as the result of 
compiling a source file. 


operand 


A constant or variable value that is manipulated in an expression. 


operator 


One or more symbols that specify how the operand or operands of an 
expression are manipulated. 


overlay 


Part of a program that is read into memory from disk only if and when 
it is needed. 
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palette 


A mapping of the color values (the actual displayable colors) to the 
legal pixel values for a given video mode. The CGA modes operate with 
a set of predetermined palettes. The EGA and VGA color modes 
operate with a redefinable palette of colors. 

parent process 


A process that generates a child process using one of the spawn, exec, 
or system families of run-time library functions. 


physical coordinates 


The coordinate system defined by the hardware. The physical- 
coordinate system has the origin (0,0) at the upper-left corner of the 
screen. The value of x increases from left to right the value of y 
increases from top to bottom. The default logical-coordinate system is 
identical to the physical-coordinate system. 


pixel 


A single dot on the screen. It is the smallest item that may be manipu- 
lated with the QuickC graphics library and it is the basic unit of the 
coordinate systems. 


pixel value 


The one-, two-, or four-bit representation of a screen pixel. It is the 
index into the palette of available colors. 


pointers 
A variable containing the address of another variable. 
pragma 


An instruction to the compiler to perform a particular action at com- 
pile time. 


precedence 


The relative position of an operator in the hierarchy that determines 
the order in which expressions are evaluated. 
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preprocessor 
A text processor that manipulates the contents of a C source file dur- 
ing the first phase of compilation. 

preprocessor directive 


See directive. 


process 
A program being executed by DOS. 


prototype 
See function prototype. 


QCL 
The command used by the Microsoft C Optimizing Compiler to com- 
pile and link programs. 

RAM disk 


An area of memory that is used to load and save files in the same way 
as a disk drive but allows more rapid access to files than a disk drive. 
Unlike a disk drive, a RAM disk is not suitable for long-term storage 
because its contents are volatile—that is, they disappear if the 
machine is powered off. 

relocatable 


Not containing absolute addresses. 


remapping 
The process of altering the correspondence between color value and 
pixel value. Only EGA and VGA palettes may be remapped. 

run time 
The time during which a previously compiled and linked program is 
executing. 

run-time library 
A file containing the routines needed to implement certain functions of 
the Microsoft C language. 

scalar types 


In C, integral, enumerated, floating-point, and pointer types. 
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scope 
The parts of a program in which an item can be referenced by name. 
The scope of an item may be limited to the file, function, block, or 
function prototype in which it appears. 

segment 
An area of memory, less than or equal to 64K long, that contains code 
or data. . 

sequence point 
A point in a C program where all expressions lexically preceding the 
point are guaranteed to have been evaluated. 

side effects 
Changes in the state of objects that occur as a result of expression 
evaluation. 

sizeof operator 
A C operator that can be used to determine the amount of storage, in 
bytes, associated with an identifier or a type. 

small memory model 
A memory model that allows for only one code segment and only one 
data segment. 

source file 


A text file containing C-language code. 


stack 


A dynamically shrinking and expanding area of memory in which data 
items are stored in consecutive order and removed on a last in, first 
out basis. 

stack probe 


A short routine called on entry to a function to verify that there is 
enough room in the program stack to allocate local variables required 
by the function and, if so, to allocate those variables. 

static 


A storage class that allows variables to keep their values even after the 
program exits the block in which the variable is declared. 
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stream functions 


Run-time library functions that treat data files and data items as 
“streams” of individual characters. 


string 


An array of characters, terminated by a null character (\0). 


string literal 


A string of characters and escape sequences delimited by double quota- 
tion marks ("'"). Every string literal has a type of “array of char,” an 
array of elements with char type. 


structure 


A set of elements, which may be of different types, grouped under a 
single name. 


structure member 


One of the elements of a structure. 


subscript expression 


An expression, usually used to reference array elements, representing 
an address that is offset from a specified base address by a given 
number of positions. 


symbolic constant 


See manifest constant. 


tag 


The name assigned to a structure, union, or enumeration type. 


ternary expression 


An expression consisting of three operands joined by the ternary 
operator (? :), used to evaluate either of two expressions depending on 
the value of a third expression. 


text color 
The color value to be used in all graphics-based text operations. 


text mode 


The file processing mode in which carriage-return—line-feed combina- 
tions are converted to a single line-feed character on input and recon- 
verted to carriage-return—line-feed combinations on output. 
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text window 
A window defined in row and column coordinates where text output to 
the screen will be displayed. 
tiling 
The process of applying a fill mask to an area of the screen. 
toggle 
The action of turning an option on or off. 


token 
The most fundamental unit of a C source program that is meaningful 
to the compiler. 

two’s complement 


A type of base-2 notation used to represent positive and negative 
numbers in which negative values are formed by complementing all 
bits and adding 1 to the results. 


type 


A description of a set of values; for example, a variable of type int can 
have any of a set of integer values within the range specified for the 
type on a particular machine. 


type cast 


An operation in which an operand of one type is converted to an 
operand of a different type. 


type checking 


An operation in which the compiler verifies that the operands of an 
operator are valid or that the actual arguments in a function call are 
of the same types as the corresponding formal parameters in the func- 
tion definition and function prototype. 


type declaration 


A declaration that defines the name and members of a structure or 
union type, or the name and enumeration set of an enumeration type. 


type name 


A specification of a particular data type that appears in variable 
declarations, in the formal-parameter lists of function prototypes, in 
type casts, and in sizeof operations. 
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typedef declaration 
A declaration that defines a shorter or more meaningful name for an 
existing C data type or for a user-defined data type. Names defined in 
a typedef declaration are often referred to as “typedefs.” 

unary expression 
‘An expression consisting of a single operand preceded or followed by a 
unary operator. 

unary operator 


An operator that takes a single operand. Unary operators in the C 
language are the complement operators (— ~ !), indirection operator 
(*), increment (++) and decrement (— —) operators, address-of opera- 
tor (&), and sizeof operator. The unary plus operator (+) is also 
implemented syntactically, but has no semantics associated with it. 
union 
A set of values that have different types and occupy the same storage 
space. 
unresolved reference 


A reference to a global or external variable or function that cannot be 
found, either in the modules being linked or in the libraries that are 
linked with those modules. 


usual arithmetic conversions 


Type conversions performed by the Microsoft QuickC Compiler on 
operands of integral or floating-point types in an expression to bring 
the operands to a common type. 

video mode 


The format used to display information on the screen. It defines the 
display characteristics. 


video page 
A screen image stored in memory. 
viewport 


A clipping region which sets the logical origin to the upper-left corner 
of the region. 
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Visibility 
The characteristic of a variable or function that describes the parts of 
the program in which it can be referenced by name. An item has global 
visibility if it is visible in all source files comprising the program; oth- 
erwise, it has local visibility in a single source file. 

visual page 


The area in memory that holds the current displayed graphics output. 


white-space character 


Characters that delimit items in a C source program, including space, 
tab, line-feed, carriage-return, form-feed, vertical-tab, and new-line 
characters. 

wild card 


One of the DOS characters (? and *) that can be expanded into one or 
more characters in file-name references. 
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* (asterisk), LIB command symbol, 244 
(bar), notational convention, xxv 
{ } (braces), notational convention, 


XXV 
[] (brackets), notational convention, 
XXV 
ae Wate notational convention, xxv 
" (double quotation marks), notational 
convention, xxv 
j omens slash)option character 
inker, 221 
QCL, 196 
- (hyphen), QCL option character, 196 
— (minus sign), LIB command symbol, 
243, 244 
—* (minus sign-asterisk), LIB command 
symbol, 244 
—+ (minus sign-plus sign), LIB 
command symbol, 244 
. (period), C operator, 68 
+ (plus sign), LIB command symbol, 
244 


; (semicolon), LIB command symbol, 
244 


80286 processor, 205 
8087 /80287 library, 19 
87.LIB, 19 


Abstract declarator, defined, 385 
/AC option (QCL), 203, 277 
Active page, defined, 385 
Add Watch... command, 178 
Addresses 

components, 273 

far, 274 

near, 274 
Aggregate type, defined, 385 
/AL option (QCL), 203, 279 

key, opening menus with, 33 

/AM option (QCL), 203, 276 
Animation 

defined, 385 

described, 108 

example program, 109 


using 
— getimage, 108 
—GPSET, 108 


INDEX 


Animation (continued) 
using (continued) 
— GXOR, 108 
_ putimage, 108 
—arc, C library function, 103 
Arcs, drawing 
described, 102 
example program, 103 
argc command-line argument, 74 
Arguments 
linker options, 221 
macros, 352 
passing by value, 57 
Argument-type list 
defined, 386 
described, 56 
argv command-line argument, 74 
Arrays 
described, 62 
example program, 63 
passing to functions, 62 
storage, 62 . 
subscripts, 62 
/AS option (QCL), 203, 275 
Aspect ratio 
calculating, 101 
defined, 100 
example program, 101 
Assembly language 
argument, definition, 294 
C, calling from, 301 
formal parameter, definition, 29-4 
interface 
C, 301 
defined, 294 
entry sequences, 296, 298 
exit sequences, 300 
local data, 296, 298 
register considerations, 297 
return value, 299 
routine, defined, 29-4 
parameter 
accessing, 297 
defined, 29-4 
passing by value, 303 
procedures 
declaration, 295 
interface, 29-4 
writing, 294 
Assignment operation, 5-t 
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ASSUME directive, 307 

Asterisk (*), LIB command symbol, 244 
AUTO C.BAT file, 13 

Automatic variables, 297 

AUX, device name, 216 


Background color, defined, 386 
Back-up procedures, 7 
Bar (|), xxv 
Base name, defined, 387 
B(ATCH) option (LINK), 224 
ibliography, xxvi 
ee SAMPLE subdirectory, 14 
locks, 54 
Bold font, xxv 
Border, defined, 100 
Bounding rectangle 
arcs, 102 
defined, 100, 387 
Braces ({ }), xxv 
Brackets (| XXxv 
Breakpoints 
adding, 182 
defined, 177 
deleting, 182 
deleting all, 177 
setting, 177 
toggling on and off, 177 
Buffers, parameter (CONFIG.SYS), 9, 
14 


Buttons 
— eircular. See Circular buttons 
command, 37 
See also Command buttons 
mouse, 21 


C language 
calling convention, 301 
passing by value, 302 
programming, 45 
/ return Vioret ‘er 
c option 199 
/C option (QCL}, 208 
Calls menu 
described, 183 
display, 183 
functions, executing, 183 
Capital letters 
small, xxv 
use of, xxv 
Case significance, linker options, 221, 
231 
cdecl keyword, 170, 171 
Center point of screen, 84 
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color graphics 
described, 88 
example program, 89 
palettes, example program, 89 
Change... command 
Cancel command button, 158, 159 
Change All command button, 159 
Change command button, 158 
Change To text box, 158 
described, 153, 158 
dialog box, 158 
errors, correcting, 159 
Find and Verify command button, 
158 
Skip command button, 158 
using, 158 
Check boxes 
choosing 
keyboard, 37 
mouse, 38 
defined, 37 
moving between, 37 
check— pointer pragma, 168 
check_ stack pragma, 169, 232 
Choosing commands, 32 
Circles, drawing, 102 
Circular buttons 
choosing 
keyboard, 38 
mouse, 38 
defined, 38 
moving between, 38 
Clear All Breakpoints command, 182 
Clear command, 151 
Clear Program List command, 133, 138 
Click 
defined, 21 
double click, defined, 2 
Clipboard 
contents 
erasing, 152 
inserting, 151 
replacing, 151 
Cut and Copy commands, 151 
defined, 150 
Clipping, defined, 387 
Clipping region, defined, 387 
.CODE directive, 295 
Code helper library, 19 
CodeView debugger 
Debug option, Compile command, 
167 


linker option for, 231 
QCL option for, 200 
Stack Trace command, 294 


/CO(DEVIEW) option (LINIX), 231 
Color 
See also Display color 
selection, 86 
text modes, 86 
value, defined, 387 
Color Graphics Adapter. See CGA 
Command buttons 
defaults, 37 
defined, 37 
executing, 37 
moving between, 37 
selecting 
keyboard, 37 
mouse, 38 
Command line 
arguments, 74 
error messages, 353 
length, 194, 364 
Commands 
Calls menu, 183 
CL, defined. See QCL command 
Exit, 23 
Help menu, 41 
notational conventions, xxv 
Comments, preserving, 208 
Compact memory model. See Memory 
models, compact 
Compilation 
conditional, 171 
error messages, 312 
Compile... command 
command buttons 
Build Program, 173 
Compile File, 174 
Rebuild All, 174 
creating 
executable files, 167 
in-memory programs, 167 
object files, 167 
Debug option, 167 
debugging, preparing for, 167 
Define text box, 172 
described, 165 
dialog box, 166 
Include text box, 172 
Language Extensions option, 170 
Optimizations option, 172 
Output Options buttons, 167 
Pointer Check option, 168 
program syntax, checking, 167 
Stack Check option, 169 
Warning Levels options, 166 
Compiler error messages 
categories, 311 
command line, 353 
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Compiler error messages (continued) 

compilation, 312 

correctable, 312 

fatal, 312 

warning, 312, 340 
Compiler limits, 352 
Compiler options. See QCL options 
Compound statements, 54 
CON, device name, 216 
Conditional compilation, 171, 172 
Conditional statements 

described, 60 

example program, 61 
CONFIG.SYS file, 14 
Constants 

defining, 172 

manifest. See Constants, symbolic 

size, Maximum, 352 

symbolic, 172 
Context, program, 30 
Context-sensitive help, 41 
Continue command 

described, 165 

shortcut key, 34 
Controlling 

linker, 221 

preprocessor, 206 

segments, 225 

stack size, 229 
Conversion, pointer arguments, 286 
Coordinate systems 

defined, 388 

described, 94 

logical coordinates, 94 

physical coordinates, 94 

program example, 95 

repositioning, 94 
Copy command 

described, 151 

shortcut key, 34 
Copying text, keyboard, 147 
Core library, 125, 388 
Correctable error messages, 312 
/CP(ARMAXALLOC) option (LINK), 

226 

Cross-reference listing, 246 
CRT0.OBJ. See Start-up routine 
Current position, defined, 388 
Current text position, defined, 388 
Cursor 

defined, 30 

moving, 146 

tab control, 121 
Cut command 

described, 151 

shortcut key, 34 
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/D option 
MAKE, 256 
QCL, 199 
Data 
segment 
data threshold, setting, 213, 289 
default, contents, 213, 289 


ypes 
declaring, 48 
storage requirements, 52 
structures, 68 
DATA directive, 295 
Debug menu 
Add Watch... command, 178 
Clear All Breakpoints command, 178 
Delete All Watch command, 177, 181 
Delete Last Watch command, 178, 
181 
listed, 178 
Screen Swapping On command, 178, 
182 


t 


shortcut keys, 178 
Toggle Breakpoint command, 177, 
178, 182 
Trace On command, 178, 182 
Debugging 
breakpoints 
adding, 182 
controlling, 182 
deleting, 182 
deleting all, 177 
setting, 177 
toggling, 177 
display output screen, 177 
execute to 
cursor location, 177 
next breakpoint, 177 
general procedure, 176 
keyboard commands, 177 
reparing for 
/CO(DEVIEW) linker option, 231 
Compile command, 167 
/Zi option (QCL), 200 
/Zq option (QCL), 200 
/Zr option (QCL), 200 
program execution, tracing, 182 
programs, restarting, 164 
QCL option for, 210 
screen swapping, 182 
watch expressions, deleting, 181 
/Zi and /Zd options, 210 
Declarations 
described, 46, 48 
maximum level of nesting, 352 
Decrement operator, 55 
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Default 
data segment 
‘contents, 175 
names, 305 
setting size, 175 
libraries, suppressing selection, 212 
Definitions, 46 
Delete All Watch command, 177, 181 
Delete Last Watch command, 181 
Deleting text 
Clear command, 151 
Copy command, 151 
Cut command, 151 
keyboard, 147 
Denormal, 358 
Device names, 226 
DGROUP, 307 
Dialog boxes 
Change... command, 158 
Compile... command, 166 
default information, 38 
defined, 35 
Edit Program List... command, 139 
Find... command, 154 
Function command, 159 
Merge... command, 136 
Open... command, 133 
options 
choosing, 37 
moving between, 36 
Options... command, 120 
Print... command, 141 
Save As... command, 137 
selecting items 
keyboard, 38 
mouse, 39 
Set Runtime Options... command, 
175 
Source... command, 118 
DIRECTION keys 
circular buttons, moving between, 38 
scrolling with, 39 
Directories 
listing contents of, 135 
names, notational conventions, xxv 
DISKCOPY utility, 7 
Disks 
backing up, 7 
compiler package, contents, 7 
contents, 7 
distribution, finding files on, 7 
Display color. See also Monochrome 
monitor, display color 
Display color, selecting, 120 
Display Options box, 121 
DOS Shell command, 133, 142 


poeSree option (LINK), 231 
ots 

Double ee defined, 21 

Drag, defined, 21 

Dynamic variables, 297 


fe option (QCL), 207 
it Menu 
Clear command, 151 
Edit menu 
Clear command, 151 
clipboard. See Clipboard 
Copy command, 151 
Cut command, 151 
described, 150 
Paste command, 151 
Read Only command, 151 
shortcut keys, 150 
Undo command, 150 
Edit Program List ...command 
command buttons 
Add/Remove, 140 
Clear List, 140 
Save List, 140 
Edit Program List... 
described, 132, 138 
dialog box, 139 
File Name list box, 139 
Files list box, 140 
program list, editing, 128 
Program List list box, 140 
Editing 
brace matching, 148 
editing keys, 145 
insert and overtype modes, 147 
place markers, setting, 148 
reversing edits, 150 
selecting text 
keyboard, 38 
mouse, 39 


command 


color graphics 
described, 90 
example program, 91 
palettes, example program, 91 
_ ellipse 
C library function, 102 
example program, 103 
Ellipsis dots (...), xxv 
EM.LIB, 19 
Emulator library, 19 
Enhanced Graphics Adapter. See EGA 
Environment table, maximum size, 364 
Environment variables 
default settings, 13, 18 
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Environment variables (continued) 
INCLUDE, 172, 199, 209 
INIT, used by MAKE, 262 
LIB, 219 
names, notational conventions, xxv 
NEW-VARS.BAT, 13 
TMP, used by LINK, 220 
EP option (QCL), 207 
QU directive, 299 
—ERESCOLOR video mode, 90 
Error window, defined, 31, 122 
Error messages 
compiler 
categories, 311 
command line, 353 
compilation, 312 
correctable, 312 
fatal, 312 
warning, 312, 340 
floating-point exceptions, 358 


LINK, 364 

MAKE, 381 

run time, 358 

run-time library, 360 

types of, 311 

warning messages, setting level of, 


Errors 

finding next, 160 

maximum number saved, 160 
Errors command, described, 122 
ESC key, closing menus, 33 
Escape sequences, 70 
Exceptions, listed, 358 
Executable files 

creating, Compile command, 167 

extensions, 167, 202 

naming 

default; 202 
QCL, using, 201 
L command, usin 
PACK) option (in), 225 

it command, 23, 13 
Exiting QuickC, 23 
Expressions 

described, 46, 54 

example program, 55 
Extensions 

executable files, 167, 202 

object files, 167, 202 

Quick libraries, 237 


far keyword 
default addressing conventions, 281 
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far keyword 
default addressing conventions, 281 
effects 
data declarations, 282 
function declarations, 285 
Language Extensions option, 
Compile command, 170 
library routines, used with, 282 
restriction for in-memory programs, 
171, 283 
small-model programs, 275 
Far pointers, 280 
/F(ARCALLTRANSLATION) option 
LINK), 229 
Fatal error messages, 312 
fclose, C library function, 72 
/Fe option (QCL), 201 
fgetchar, C library function, 72 
Figures 
displaying from memory 
described, 106 
example program, 107 
example program, 103 
saving to memory 
described, 106 
example program, 107 
File menu 
ae List command, 128, 
1 


described, 131 

DOS Shell command, 142 

Edit Program List... command, 128, 
138 


Exit command, 142 

Merge... command, 136 

New command, 128, 133 

Open... command, 133 

Open Last File command, 136 

Print... command, 141 

Save As... command, 137 

Save command, 137 

Set Program List... command, 128, 
138 


shortcut keys, 132 
File names 
extensions, 195 
notational conventions, xxv 
uppercase and lowercase letters in,’ 


Files 
AUTOEXEC.BAT, 13 
backing up, 7 

closing, 72 


CONFIG.SYS, 14 
distribution disks, finding on, 7 
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Files (continued) 
executable 
naming with QCL, 201 
QCL command, used with, 192 
I/O functions 
described, 72 
example program, 73 
formatted input, 72 
formatted output, 72 
single character I/O, 72 
listing, preprocessed, 207 
loading 
keyboard, 135 
most recently edited, 136 
mouse, 135 


map 
created by Debug option, 167 
creating, 231 
described, 201 
example, 226 
listing formats, 226 
merging, 136 
number open, maximum, 364 
object 
defined, 394 
QCL command, used with, 191 
opening, 72 
PACKING.LST, 7 
parameter (CONFIG.SYS), 9 
printing, 141 
QC.INI, 25 
saving, 137 
size, maximum, 364 
source, defined, 397 
temporary, space requirements, 352 
Files parameter (CONFIG.SYS), 14 
Fill flag, defined, 100 


Fill mask 
creating, 104 
defined, 390 


example program, 105 
Filling, defined, 390 
Find... command 
described, 153, 154 
dialog box, 154 
Find What text box, 154 
Match Upper/Lowercase option, 155 
Regular Expression option, 155 
Whole Word option, 154 
Finding text, 154 
Floating point 
not loaded, 361 
operations 
error messages, 358 
exceptions, 358 


Floating point (continued) 
options 
default libraries, 205 
selecting, 204 
— floodfill, C library function, 104 
/Fm option oan) 201 
/Fo option (QCL), 202 
fopen, C library function, 72 
for, C keyword 
described, 58 
example program, 59 
Foreground color, defined, 390 
Formal parameters, 57 
Format specifiers, prefixes, 180 
Format string, 71 
fortran keyword, 170 
Forward slash (/), option character 
linker, 221 
QCL, 196 
/FPi option We 204. 
/FPi87 option L), 204 
fputchar, C aoa ‘unction, 72 
F'ramepointer, 296 
Function 
declarations 
described, 56 
example program, 57 
near and far keywords, 285 
definitions 
described, 56 
example program, 57 
prototyping, 56 
Function command 
described, 159 
dialog box, 159 
Functions and arrays, 62 
Functions, defined, 46 


/GO option 205 
/G2 option (QCL), 205 
/Gc option (QCL), 212 
Generic functions, 66 
getchar, C library function 
described, 70 
example program, 71 
_ getfillmask, C library function, 104 
— getimage, C library function, 106 
— getlogcoord, C library function, 95 
— getphyscoord, C library function, 95 
— gettextcolor, C library function, 86 


QCL), 


. getvideoconfig, C library function, 80, 
84 


graph.h, graphics library, 80 
Graphics 
introduction, 79 
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Graphics (continued) 
library, 80 
program structure 
described, 80 
example, 81 
references, 79 
GRAPHICS.LIB, 20 
GROUP directive, 307 
/Gs option (QCL), 199, 232 
/Gt option (QCL), 213, 289 


Help menu, 40, 41 
/HELP o tion 
ane (i), 222 


_Hnesi6COLOR, video mode, 90 
Hyphen ‘ -), QCL option character, 196 
Hypocycloids, 96 


/I option 
MAKE, 256 
QCL, 199 
Identifiers 
length, maximum, 352 
predefined 
listed, 206 
M_ 186, 206 
M_ 1I86mM, 206 
MSDOS, 206 
NO_EXT_ KEYS, 171, 206 
removing definitions of, 206 
if, C keyword 
described, 60 
example program, 61 
Ignoring case, 231 
Include command, described, 119 
Include files 
directory specification, 172, 199, 209 
.MAK files, dependencies in, 263 
nesting, maximum level of, 352 
search path, 199, 209 
# include, preprocessor directive, 50 
INCLUDE environment variable, 
overriding, 172, 199, 209 
Increment operator, 55 
Inexact, 358 
Inference rules, 260 
{i NFORMATION) option (LINK), 223 
T environment variable, used by 
MAKE, 262 
Input focus 
changing, 36 
defined, 35 
Insert mode, 147 
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Inserting text 

insert mode, 147 

keyboard, 146 

Paste command, 151 
Instruction sets 

80286 processor, 205 

8086/8088 processor, 205 
I/O functions 

escape sequences, 70 

example program, 71, 72 

file, 72 

format string, 71 

formatted input, 70, 72 

formatted output, 70, 72 

fprintf, 72 

fscanf, 72 

printf, 70 

scanf, 70 

single character, 70 
Italics, xxiv 


Keywords 
cdecl, 170, 171 
defined, 391 
far. See far keyword 
fortran, 170 
near. See near keyword 
pascal, 170 
special, 170 


1 option (QC), 238 
anguage extensions 
disabling 
Language 170 
/Za option (QCL), 199 
listed, 170 
Large memory model. See Memory 
models, large 
LDFLAGS macro, 264 
Leaving QuickC, 23 
LIB 


combining libraries, 243 
command symbols 
asterisk (*), 244 
minus sign C ), 243, 244 
minus sign-asterisk (—*), 244 
minus sign-plus sign (4), 244 
plus sign (+), 243, 244 
environment variable 
stand-alone-library search path, 
19 


user-library search path, 238 
error messages, 376 
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LIB (continued) 


library modules 
adding, 243 
deleting, 243 
extracting, 244 
extracting and deleting, 244 
replacing, 244 
listing files, 246 
options 
e size, specifying, 247 
IPI GESIZE), 247 
response file, ey, 
running 
command line, 240 
prompts, 240 


LIBH.LIB, 19 


Libraries 


core, 125, 388 
creating, ‘compiling modules with /Z1, 
212 


default 
See also Default, libraries 
/FP and /A options, 203 
ignoring, 219, 225 
suppressing selection, 212 
defined, 392 
graphics, 20 
GRAPHICS.LIB, 20 
Quick. See Quick libraries 
routines, built into QuickC 
environment, 239 
run time, defined, 396 
search path, 219 
SETUP 


math packages, choosing, 10 

memory models, choosing, 10, 15 
stand-alone 

changing, 240 

combining, 243 

creating, 240 

LIB command line, 243 

listing, 246 

object modules, deleting, 243 

object modules, extracting and 

deleting, 244 

object modules, including, 243 

object modules, replacing, 244 
standard places, 219 
uncombined 

8087 /80287 processor, 19 

87.LIB, 19 

code helper, 19 

combined libraries, corresponding, 


19 
EM.LIB, 19 
emulator, 19 


Libraries (continued) 
uncombined (continued) 
floating poe 19 
LIBH.LIB, 1 
MLIBFP LIB, 19 
reasons for using, 18 
standard, 19 
user. See Quick libraries 
Library manager. See LIB 
Limits 
compiler, 352 
run time, 363 
Line style, defined, 392 
/LI(NENUMBERS) option (LINK), 
226, 231 
Lines 
drawing 
described, 98 
example program, 99 
patterned, 98 
~ lineto, C library function, 98 
NK 


error messages, listed, 364 
response file, 215 
temporary output ee 220, 222 
link option (QCL), 1 
inker options 
abbreviations, 221 
/BATCH (/B), 224 
case sensitivity, 221, 231 
/CODEVIEW (/CO), 231 
command line, order on, 221 
ij CPARMAXALLOC / CP), 226 
debugging with CodeView debugger, 
231 


default libraries, ignoring, 219, 225 
displaying 
line numbers, 231 
process information, 223 
/DOSSEG ee 231 
IEXEP ACI 2295 
) ae es NSLATION (/F), 


/HELP ( i222 

INE bf TATION (/ (a) 223 
LINENUMBERS (/LI), 226, 231 
inker prompting, preventing, 224 
listing, 222 

.MAK files, using, 264 


/ (Node ACL ALiRar SEARCH 
/NOFARCALLTRANSLATION 


INCIGNOREGASE ( NON), 231 
/NOPACKCODE (/NOP), 230 
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Linker options (continued) 
numerical arguments, 221 
overlay interrupt, setting, 233 
if OVERLAYINTERRUPT (/O), 233 
/PACKCODE (/PAC), 230 
packing contiguous segments, 230 

aragraph space, allocating, 226 
/PAUSE (/PAU), 222 
pausing, 222 
Quick library, creating, 224 
/QUICKLIB (/Q), 224 
segments 

controlling, 225 

ordering, 231 
/SEGMENTS (/SE), 225 
stack size, setting, 229 
/STACK UST), 229 
translating far calls, 229 

Listing files 
cross-reference (LIB), 246 
preprocessed, 207 

Logical origin, defined, 392 

Logical-coordinate system, 94, 392 

Loop optimization, 213 

Looping statements 
described, 58 
example program, 59 


Macro Assembler 
See also Assembly language 
EQU directive, 299 
Macro definitions 
MAKE, 257 
size, maximum, 352 
Macros 
arguments, maximum number, 352 
defined, 172 
notational conventions, xxv 


include file dependencies, 263 
LDFLAGS macro, 264 
MAKE utility, used with, 263 


specifying linker options in, 264 
MAKE 


described, 251 
error messages, 381 
inference rules, 260 
macro 
definitions, 257 
names, special, 260 
messages, 255 
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MAKE (continued) 
options (continued) © 
/S, 256 
using, 256 
/X, 256 
running, 255 
Manifest constants, notational 
conventions, xxv 
Map files 
creating 
Debug option, 167 
example, 226 
/LI option (LINK), 231 
extension, 231 
format, 226 
program entry point in, 228 
segment lists in, 226 
symbol tables in, 227 
aw ) option (LINK), 226 
M. See Assembly language 
MASM interface, 293 
Medium memory model. See Memory 
models, medium 
Memory addresses. See Addresses 
Memory models 
compact, 203, 277, 388 
default, 273, 275 
large, 203, 279, 392 
medium, 203, 276, 393 
mixed. See Mixed memory models 
options 
compact model, 277 
default libraries, 205 
large model, 279 
medium model, 276 
small model, 275 
QCL options, 203 
small, 203, 275 
standard 
advantages, 274 
common features, 275 
disadvantages, 274 
Memory requirements, xxii 
Menu bar, 30 
Menus 
Calls, 183 
canceling, 33 
choosing commands from, 32 
closing, 33 
Debug, 178 
displaying, 33 
Edit, 149 
File, 131 
Help, 40 
opening, keyboard, 33 
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Menus (continued) 
enero described, 32 
Run, 16 
Search, 152 
Merge... command 
described, 132, 136 
dialog box, 136 
M_ 186, 206 
M_I86mM, 206 
Microsoft LIB. See LIB 
Microsoft segment model, 305 
Minus sign (—), LIB command symbol, 
243 
Minus sign-asterisk (—*), LIB command 
symbol, 244 
Minus sign-plus sign (-+), LIB 
command symbol, 244 
Mixed memory models, 280, 281 
Mixed-language programming, 293 
mLIBFP.LIB, 19 
-MODEL directive (MASM), 295, 303 
Modules 
compiling, 173 
creating, 133 
defined, 125 
program list 
adding to, 128 
deleting from, 128 
Modules, object. See Object modules 
Monocots monitor, display color, 
121 
Mouse 
button, 21 
check boxes, using with, 38 
circular buttons, using with, 38 
commands, canceling, 33 
compatible types, 21 
cursor, moving, 148, 149 
dialog boxes, using with, 38 
loading files with, 135 
pointer, 30 
scrolling with, 39 
selecting 
commands, 33 
selecting text with, 39, 149 
terms 
defined, 21 
using, 21 
—moveto, C library function, 96, 98 
_~MRES16COLOR video mode, 90 
— MRES256COLOR video mode, 92 
—MRES4COLOR video mode, 88 
~MRESNOCOLOR video mode, 89 
MSDOS identifier, 206 
Multiple-module programs, 127 


N option (MAKE), 256 
ames 
device, 226 
executable files, 201 
object files, 202 
segment, changing, 289 
NAN (not a number), defined, 394 
near keyword 
default addressing conventions, 281 
effects in 
data declarations, 282 
function declarations, 285 
Language Extensions option, 
Compile command, 170 
library routines, used with, 282 
Near pointer, 280 
Nesting 
declarations, 352 
include files, 352 
preprocessor directives, 352 
New command, described, 132, 133 
NEW-CONEF-.SYS file, 9, 13 
NEW-VARS.BAT file, 9, 13 
Next Error command 
described, 153, 160 
shortcut key, 34 
/NOD(EFAULTLIBRARYSEARCH) 
option EN: 219, 225 
KEYS identifier, 171, 206 
i NOF(ARCALLTRANSLATION 
tion (LINK), 229 
/NOIGNO ECASE) option (LINK), 


(NOPOKCORE) tion (LINK), 230 
ot a Number (N. Y satived aa 
Notation, debed XXIV 
NT option (QCL), 289 

, device name, 216 
NULL segment, 361 
Null-pointer assignment, 361 


Object files 
creating, Compile command, 167 
defined, 394 
extensions, 167, 202 
naming, 202 
object modules, difference from, 243 
QCL command, used with, 191 
Object modules 
defined, 240, 243 
library 
deleting from, 243 
including in, 243 
listing, 246 
object files, difference from, 243 


Index 


/Ol option (QCL), 213 
Open... command 
described, 132, 133 
dialog box, 134 
File Name list box, 134 
list. boxes 
listing files with, 136 
loading files with, 135 
Open Last File command, 132, 136 
Operators, 54 
Optimization 
loops, 213 
maximum, 199 
option, Compile.. . command, 172 
/Ot option (QCL), 199 
/Ox option (QCL), 199 
speed, 199 © 
Optional fields, notational conventions, 


XXV 
Options, choosing from dialog box, 37 
Options... command 

described, 119 
dialog box, 120 
Normal Text option, 120 
Scroll Bars option, 121 
Tab Stops option, 121 
Options, linker. See Linker options 
Options, QCL. See QCL options 
/Ot option (QCL), 199 
Output Screen command, 121 
—outtext, C library function, 86 
f /O(VERLAYINTERRUPT) op tion’ 
(LINK), 233 
Overlays 
defined, 394 
interrupt number, setting, 233 
overlay manager prompts, 234 
restrictions, 233 
search path, 234 
specifying (LINK), 233 
Overtype mode, 30, 147 
/Ox option (QCL), 939 


/P option (QCh), 207 
pack pragma : 
PPAC(KCODE) Selick (LINIX), 230 
acking structure members, 210 
PACKING.LST file, 7 
Page size, library, 247 
PIAGESIZK) option (LIB), 247 
alettes 
CGA, 88 
defined, 395 
EGA, 90 
VGA, 92 
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Paragraph space, 226 
Parameters 
assembly, accessing from, 297 
passing by value, 303 
pascal keyword, 170 
Passing by value 
arguments to functions, 57 
assembly-language example, 303 
C parameters, 302 
Paste command 
described, 151 
shortcut key, 34 
pe command, MAKE, used with, 
57 
Path names 
notational conventions, xxv 
QCL command line, 195 
Patterns, 104 
PAU(SE) option (LINK), 222 
eriod (.), C operator, 68 
Physica. coordinates 
defined, 395 
described, 94 
—pie 
C library function, 103 
example program, 103 
Pies, drawing, 102 
Pixel, defined, 395 
Pixel values 
defined, 395 
text modes, 86 
Place markers, 148 
Placeholders, xxiv 
Plus sign (+), LIB command symbol 
specifying library, 244 
using, 243 
Pointers 
arguments, size conversion, 286 
creating, 64 
described, 64 
example program, 65 
far, 280 
functions, 66 
functions, to 
described, 66 
example program, 66 
invalid, checking for 
Pointer Check option, Compile 
command, 168 
/Zr option (QCL), 200 
manipulations, 65 
near and near keywords, 280 
operators, 64 
relationship to 
functions, 64 
strings, 65 
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Pointers (continued) 
relationship to (continued) 
structures, 69 
storage requirements, 64 
structures, 69 
Pointing, defined, 21- 
Points 
example program, 97 
plotting, 96 
Pragmas 
check pointer, 168 
check_ stack, 169, 232 
pack, 210 
Prefixes, format specifiers, used with, 
180 
Preprocessor 
directives 
described, 46, 50 
example program, 51 
macro arguments, maximum number 
of, 352 
macro definition, maximum size of, 
352 
nesting, maximum level of, 352 


efine, Compile command, 172 
Include, Compile command, 172 
predefined identifiers, removing 

definitions of, 206 
preserving comments, 208 
using, 205 

Press, defined, 21 
Previous Error command, described, 
153 
Print... command 
described, 133, 141 
dialog box, 141 
Print File option, 142 
Print Selected Text option, 142 
printf, C library function, example 
program, 71 
PRN, device name, 216 
Processors 
80286, 205 
8086/8088, 205 


| Program context, 30 


Program List... command 
command buttons 
Clear List, 128 
Program lists 
changes, saving, 140 
clearing 
Clear List command button, 140 
Clear Program List command, 128, 
138 


Program lists (continued) 
clearing (continued 
New... command, 128 
New command, 133 
creating, 128, 138 
defined, 125 
disk file, 128 
editing, 128, 141 
modules 
adding, 140 
deleting, 140 
viewing, 128 
Program structure, 46 
Program-maintenance utility. See 
MAKE 


Programs 
compiling, 165, 173 
creating, 133 
execution 
continuing, 165 
tracing, 182 
multiple module, 127 
restarting, 164 
running, 164 
single module, 125 
Prototyping, 56 
PUBLIC directive, 295 
Public symbols, listing, 246 
putchar, C library function, 70 
— putimage, C library function 
action-verb argument, 106 
using, 106, 107 


QC command, starting QuickC, 22 
QC options 
1, 238 
oad Quick library, 238 
QC.INI file, 25 
QCL 


command, defined, 396 
options 
/Zd, 231 
/Zi, 231 
QCL command 
filename extensions, 195 
specifying file names, 194 
QCL options 
80286 processors, using, 205 
/AC, 203, 277 
/AL, 203, 279 
/AM, 203, 276 
/AS, 203, 275 
/c, 199 
/C, 208 
case sensitivity of, 196 
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QCL options (continued) 


command line, order on, 196 
comments, preserving, 208 
Compile dialog box, similarity to, 198 
constants and macros, defining, 198 
/D, 199 
data threshold, setting, 213, 289 
debugging 
CodeView debugger, using, 200 
preparing for, 210 
default libraries, 205 
/E, 207 
/EP, 207 
/F, 201 
/Fe, 201 
floating point, default libraries, 205 
/Fm, 201 
/Fo, 202 
format, 196 
/FPi, 204 
/FPi87, 204 


include files, searching for, 199, 209 
line numbers, 200, 210 
junk, 193 
isting, 201 
map files, 201 
memory models 
compact, 277 
default libraries, 205 
large, 279 
medium, 276 
small, 275 
naming 
executable files, 201 
object files, 202 
/NT, 289 
object file, naming, 202 
/Ol, 213 
optimization 
loops, 213 
maximum, 199 
speed, 199 
option characters 
forward slash (/), 196 
hyphen (-), 196 
/Ot, 199 
/Ox, 199, 232 
/P, 207 
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QCL options (continued) 
predefined identifiers, removing 
definitions of, 206 
preprocessed listing, 207 
preprocessor, 205, 206, 208 
special keywords, turning off, 281 
structure members, packing, 210 
suppressing, library selection, 212 
syntax checking, 200 
text segments, naming, 289 
/U, 206 
/u, 206 
/W, 199 
/Za, 199, 281 
d, 210 
/Zi, 200, 210 
/Z\, 212 
/Zp, 210 
/Zq, 200 
/Zr, 200 
/Zs, 200 
qsort, C hbrary function, 66 
Quick libraries 
creating, 224, 237 
defined, 237 
extensions, 237 


loading, 238 
standard library routines, using in, 


QuickC commands 
Add Watch..., 178 
canceling with 

keyboard, 33 
mouse, 33 

Change..., 158 
Clear, 151 
Clear All Breakpoints, 182 
Clear Program List, 133 
Compile..., 164, 165 
Continue, 163, 165 
Copy, 151 
cursor movement, 146 
Cut, 151 
Delete All Watch, 181 
Delete Last Watch, 181 
DOS Shell, 133, 142 
Edit menu, 149 
Edit Program List..., 132, 138 
Errors, 117, 122 
Exit, 133, 142 
File menu, 131 
Find..., 153, 154 
Function, 159 
Include, 117, 119 
Merge..., 132, 136 
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QuickC commands (continued) 
New, 132, 133 
Next Error, 160 
Open..., 132, 133 
Open Last File, 132, 136 
Options..., 117, 119 
Output Screen, 117, 121 
Paste, 151 
Previous Error, 153 
Print..., 133, 141 
Read Only, 151 
Repeat Last Find, 155 
Restart, 163, 164 
Save, 132, 137 
Save As..., 132, 137 
Screen Swapping On, 182 
Selected Text, 155 
selecting 
keyboard, 33 
mouse, 33 
Set Program List..., 132 
Set Runtime Options..., 164, 174 
shortcut keys, 34 
Source..., 117 
Start, 163, 164 
Toggle Breakpoint, 182 
Trace On, 182 
Undo, 150 
/Q(UICKLIB) option (LINK), 224 
Quotation marks (“”) and """, xxv 


RAM required, xxii 
Read Only command, 152 
Rectangle 
drawing, 102 
example program, 103 
—rectangle, C library function, 102 
Register variables, 53 
Regular expressions, 156 
Relocatable, defined, 396 
—remapallpalette, C hbrary function, 
90, 93 
_remappalette, C library function, 90, 
93 
Remapping, defined, 396 
Repeat Last Find command 
described, 153, 155 
shortcut key, 34 
Replacing text, 158 
Response file 
LIB, 242 
LINK, 215 
Restart command, described, 164 
Return types, 56 


Run menu 
Compile... command, 164, 165 
Continue command, 163, 165 
described, 163 
Restart command, 163, 164 
Set Runtime Options... command, 
164, 174 
shortcut keys, 163 
Start command, 163, 164 
Run-time error messages 
described, 358 
run-time library, 360 
Run-time limits, 363 


f S option (MAKE), 256 
Save As... command 
described, 132, 137 
dialog box, 137 
File Name text box, 137 
Save command 
described, 132, 137 
File Name text box, 137 
scanf, C library function, example 
program, 71 
Scope, variable declarations, 52 
Screen 
description, 29 
elements, controlling, 121 
Screen Swapping On command, 182 
Scroll bars 
controlling, 121 
defined, 30 
Scroll box, 39 
Scrolling 
defined, 39 
keyboard, 39, 146 
mouse, 39, 148 
text boxes, 135 
Search menu 
Change... command, 153, 158 
Find... command, 153, 154 
Function command, 153, 159 
Next Error command, 153, 160 
Previous Error command, 153 
Repeat Last Find command, 153, 155 
Selected Text command, 153, 155 
shortcut keys, 153 
Search paths 
# include directive, 50 
include files, 172, 199, 209 
libraries, 219 
overlays, 234 
SEGMENT directive, 306 
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Segments 
data 
data threshold, effect of, 213, 289 
default, 175 
default, 273 
defined, 273 
listed, 306 
lists, in map files, 226 
names, changing, 289 
NULL, 361 
number allowed, 225 
~ order, 231 
text 
ane pie 289 


/SE(GMEN'TS) ee EIN 22 
Selected Text comman 
described, 153, 155 
shortcut key, 34 
Selecting text 
cursor, 149 
keyboard, 38, 146 
mouse, 39 
—Sselectpalette, C library function, 88 
Semicolon (;), LIB command symbol, 
244 
Set Program List... 
132, 138 
Set Runtime Options... command 
Command Line option, 175 
described, 174 
dialog box, 175 
Near Data option, 175 
Stack option, 175 
—setfillmask, C library function, 104 
~ setlinestyle, C library function, 98 
— setlogorg, C library function, 94 
~ setpixel, C library function, 96 
—settextcolor, C library function, 86 
SETUP 
disk, 8 
installation directories, choosing, 10, 


command, 128, 


math packages, choosing, 9 

memory models, choosing, 10, 15 

operations, 8 
—setvideomode, C library function, 82 
SHIFT key, selecting text, 38 
SHIFT+TAB key sequence, moving 

between check boxes, 37 

Shortcut keys 

Change... command, 158 

Clear command, 150 

Continue command, 163 

Copy command, 150 

Cut command, 150 
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Shortcut keys (continued) 
Find... command, 154 
listed, 34 
Next Error command, 160 
Open Last File command, 132, 136 
Paste command, 150 
Previous Error command, 160 
Repeat Last Find command, 155 
Selected Text command, 155 
Toggle Breakpoint command, 178, 
182 


Single-module programs, 125 
Small capitals, xxv 
Small memory model 
procedures, setting up, 295 
Small memory model. See Memory 
models, small 
Source... command 
described, 117 
dialog box, 118 
Source file, defined, 397 
SPACEBAR 
check boxes, choosing, 37 
command buttons, executing, 37 
Special keywords, turning off, 281 
Special macro names (MAKE), 260 
Stack 
defined, 397 
frame, 296, 298 
overflow, 361 
probes, 169, 397 
variables, 297 
Stack checking 
disabling 
Compile command, 169 
/Gs option (QCL), 199 
enabling, 169 
/ST(ACK) option (LINK), 229 
Stack size 
default for C programs, 175 
setting 
/F option (QCL), 201 
Stack option, Set Runtime 
Options... command, 175 
Stack Trace, CodeView feature, 294 
Standard places 
ignoring, 209 
libraries, 219 
Start command 
described, 164 
shortcut key, 34 
Starting QuickC, 21 
Start-up routine, 226, 229 
Statement format, 54 
Statements, 46, 54 
Status line, 30 
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Strings 

defined, 62 

length, maximum, 352 

notational conventions, xxv 
Structure of programs 

described, 46 

example program, 46 
Structures 

creating, 68 

packing, 210 

pointers, 69 

program example, 69 

variables within, 68 
Subdirectories, \ BIN\ SAMPLE, 14 
Subscripts, 62 
switch, C keyword 

described, 60 

example program, 61 
Switches. co Options 
Symbol tables 

map files, used in, 227 

object files, used in (/Zi option), 210 
Syntax 

described, xxiv 

help, 40 
System requirements, xxii 


TAB key 
input focus, changing, 36 
moving between 
check boxes, 37 
command buttons, 37 
Tab stops, controlling, 121 
Temporary files, 352 
Text 
boxes 
defined, 36 
errors, correcting, 36 
scrolling, 135 
color 
defined, 398 
example program, 87 
copying, keyboard, 147 
deleting 
Clear command, 151 
Copy command, 151 
Cut command, 151 
keyboard, 147 
finding, 154 
inserting 
insert mode, 147 
keyboard, 146 
Paste command, 151 
modes, 86 
replacing, 158 


Text (continued) 
scrolling 
keyboard, 39, 146 
mouse, 39, 149 
selecting 
keyboard, 38, 146 
mouse, 39, 148 
Text segment 
default name, 289 
naming, 289 
~ TEXT segment, 289 
Text window, defined, 399 
Tiling, defined, 399 
Title bar, 30 
TMP environment variable (LINK), 
220 


Toggle Breakpoint command, 177, 182 


TOOLS.INI file, 261 

Trace On command, 182 

Two’s complement, defined, 399 
Type conversions, 55 

Type definitions, 48 

typedef, C keyword, 48 


‘u option (QCL), 206 

nderflow, 358 
Undo command 

described, 150 

shortcut key, 34 
Uppercase letters, use of, 194 
Uppercase letters, use of, xxv 
Utilities, library manager. See LIB 


/U option (esr 206 


Value parameters, C, 302 
Variable declarations 
data types, 52 
register variables, 53 
scope, 52 
storage requirements, 52 
Vectors, defined, 100 
Vertical bar (|), xxv 
VGA 


color graphics 

described, 92 

example program, 93 
color manifest constants, 93 
palettes, example program, 93 

Video configuration 

accessing, 84 
determining, 80 
elements, 84 
example program, 85 
structure, 84 
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Video Graphics Array. See VGA 
Video mode 
~DEFAULTMODE, 82, 83 
defined, 400 
described, 82 
setting 
described, 80, 82 
example program, 83 
Video page, defined, 400 
View menu 
described, 117 
Errors command, 117, 122 
Include command, 117, 119 
Options... command, 117, 119 
Output Screen command, 117, 121 
Source... command, 117 
View window, defined, 30 
Viewport, defined, 400 
Visual page, defined, 401 
VM.TMP file, 220, 222 
~ VRES16COLOR (video mode), 92 


Warning error messages 
described, 312 
listed, 340 
setting level of, 166 
Watch expressions 
adding, 178 
defined, 176 
deleting, 181 
format specifiers, 179 
scope, 181 
Watch window, defined, 31, 176 
while, C keyword 
described, 58 
example program, 59 
Windows 
error, 31, 122 
view, 30 
watch, 31 


option 
PR epee 256 

QCL, 209 
/Za option (QCL), 199, 281 
/Zd option (QCL), 210, 231 
/Zi option (QCL), 200, 210, 231 
/Z\ option (QCL), 212 
/Zp option (QCL), 210 
/Zq option (QCL), 200 
/Zr option (QCL), 200 
/Zs option (QCL), 200 
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